Fix #120

SysML2.NET.Tests/Extend/DocumentationExtensionsTestFixture.cs

@@ -1,38 +1,61 @@
-// -------------------------------------------------------------------------------------------------
+// -------------------------------------------------------------------------------------------------
 // <copyright file="DocumentationExtensionsTestFixture.cs" company="Starion Group S.A.">
-// 
+//
 //   Copyright 2022-2026 Starion Group S.A.
-// 
+//
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
 //   You may obtain a copy of the License at
-// 
+//
 //        http://www.apache.org/licenses/LICENSE-2.0
-// 
+//
 //    Unless required by applicable law or agreed to in writing, software
 //    distributed under the License is distributed on an "AS IS" BASIS,
 //    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 //    See the License for the specific language governing permissions and
 //    limitations under the License.
-// 
+//
 // </copyright>
 // ------------------------------------------------------------------------------------------------
 
 namespace SysML2.NET.Tests.Extend
 {
     using System;
-    
+
     using NUnit.Framework;
-    
+
     using SysML2.NET.Core.POCO.Root.Annotations;
+    using SysML2.NET.Core.POCO.Root.Elements;
+    using SysML2.NET.Core.POCO.Systems.DefinitionAndUsage;
+    using SysML2.NET.Exceptions;
+    using SysML2.NET.Extensions;
 
     [TestFixture]
     public class DocumentationExtensionsTestFixture
     {
         [Test]
-        public void ComputeDocumentedElement_ThrowsNotSupportedException()
+        public void VerifyComputeDocumentedElement()
         {
-            Assert.That(() => ((IDocumentation)null).ComputeDocumentedElement(), Throws.TypeOf<NotSupportedException>());
+            Assert.That(() => ((IDocumentation)null).ComputeDocumentedElement(),
+                Throws.TypeOf<ArgumentNullException>());
+
+            // Fresh Documentation has no owning relationship, so the documented element cannot be
+            // resolved — the implementation must throw IncompleteModelException (Option A path).
+            var emptyDoc = new Documentation();
+
+            Assert.That(() => emptyDoc.ComputeDocumentedElement(),
+                Throws.TypeOf<IncompleteModelException>());
+
+            // Populated case: wire a Definition as the owner of the Documentation via an Annotation.
+            // After AssignOwnership, documentation.OwningRelationship.OwningRelatedElement == target,
+            // so ComputeDocumentedElement() must return target.
+            var target = new Definition();
+            var annotation = new Annotation();
+            var doc = new Documentation();
+
+            target.AssignOwnership(annotation, doc);
+
+            Assert.That(doc.ComputeDocumentedElement(), Is.SameAs(target));
         }
     }
 }

SysML2.NET/Extend/DocumentationExtensions.cs

@@ -21,10 +21,9 @@
 namespace SysML2.NET.Core.POCO.Root.Annotations
 {
     using System;
-    using System.Collections.Generic;
 
     using SysML2.NET.Core.POCO.Root.Elements;
-    using SysML2.NET.Core.POCO.Root.Namespaces;
+    using SysML2.NET.Exceptions;
 
     /// <summary>
     /// The <see cref="DocumentationExtensions"/> class provides extensions methods for
@@ -33,18 +32,30 @@
     internal static class DocumentationExtensions
     {
         /// <summary>
-        /// Computes the derived property.
+        /// Computes the derived property <c>documentedElement</c>.
         /// </summary>
+        /// <remarks>
+        /// Documentation is a Comment that specifically documents a documentedElement, which must be its owner.
+        /// The <c>documentedElement</c> property redefines <c>annotatedElement</c> with cardinality 1..1 and
+        /// subsets <c>owner</c>. The documented element is therefore the owner of the Documentation, accessed
+        /// via <c>owner</c> (derived as <c>owningRelationship.owningRelatedElement</c>).
+        /// </remarks>
         /// <param name="documentationSubject">
         /// The subject <see cref="IDocumentation"/>
         /// </param>
         /// <returns>
-        /// the computed result
+        /// The <see cref="IElement"/> that is documented by this <see cref="IDocumentation"/>
         /// </returns>
-        [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
         internal static IElement ComputeDocumentedElement(this IDocumentation documentationSubject)
         {
-            throw new NotSupportedException("Create a GitHub issue when this method is required");
+            if (documentationSubject == null)
+            {
+                throw new ArgumentNullException(nameof(documentationSubject));
+            }
+
+            return documentationSubject.owner
+                   ?? throw new IncompleteModelException(
+                       $"{nameof(documentationSubject)} must have an owner (its documentedElement)");
         }
 
     }