XDoc Refactoring (#21)

Author: a-gubskiy

src/BitzArt.XDoc/BitzArt.XDoc.csproj

@@ -17,18 +17,15 @@
         <PackageReadmeFile>README.md</PackageReadmeFile>
         <PackageIcon>xdoc-logo.png</PackageIcon>
     </PropertyGroup>
-
-    <ItemGroup>
-        <None Include="..\..\assets\xdoc-logo.png" Pack="True" Visible="false" PackagePath="\"/>
-        <None Include="..\..\README.md" Pack="True" Visible="false" PackagePath="\"/>
-    </ItemGroup>
-
+    
     <ItemGroup>
         <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
             <_Parameter1>BitzArt.XDoc.Tests</_Parameter1>
         </AssemblyAttribute>
-    </ItemGroup>
 
+        <AssemblyAttribute Include="JetBrains.Annotations.PublicAPIAttribute" />
+    </ItemGroup>
+            
     <ItemGroup>
         <None Include="..\..\assets\xdoc-logo.png" Pack="True" Visible="false" PackagePath="\"/>
         <None Include="..\..\README.md" Pack="True" Visible="false" PackagePath="\"/>

src/BitzArt.XDoc/Models/!MemberDocumentation.cs

@@ -1,5 +1,4 @@
 using System.Xml;
-using BitzArt.XDoc.Resolvers;
 
 namespace BitzArt.XDoc;
 
@@ -9,6 +8,8 @@ namespace BitzArt.XDoc;
 /// </summary>
 public abstract class MemberDocumentation
 {
+    private readonly Dictionary<XmlNode, DocumentationReference?> _references = [];
+    
     // Documentation of a code member:
     // - Type as a member of an Assembly;
     // - MemberInfo as a member of Type.
@@ -18,39 +19,46 @@ public abstract class MemberDocumentation
     /// </summary>
     public XmlNode? Node { get; private init; }
 
-    internal XDoc Source { get; private init; }
-
-    private bool _isResolved = false;
-    private InheritanceMemberDocumentationReference? _inherited;
-    private IReadOnlyCollection<MemberDocumentationReference>? _references;
+    public XDoc Source { get; private init; }
 
-    /// <summary>
-    /// Contains references to inherited documentation.
-    /// </summary>
-    public InheritanceMemberDocumentationReference? Inherited
+    private bool IsMyNode(XmlNode node)
     {
-        get
+        while (node.ParentNode != null)
         {
-            OnRequireResolve();
+            if (node.ParentNode == Node)
+            {
+                return true;
+            }   
 
-            return _inherited;
+            node = node.ParentNode;
         }
-    }
 
-    /// <summary>
-    /// Contains references to other documentation.
-    /// </summary>
-    public IReadOnlyCollection<MemberDocumentationReference> References
+        return false;
+    }
+    
+    public DocumentationReference? GetReference(XmlNode node)
     {
-        get
+        // // <dsffsf cref="BitzArt.XDoc.Models.TypeDocumentation" /> 
+        // // <inheritdoc cref="Name" /> 
+        // // <inheritdoc /> 
+        
+        if (_references.TryGetValue(node, out var result))
         {
-            OnRequireResolve();
+            return result;
+        }
 
-            return _references!;
+        if (!IsMyNode(node))
+        {
+            throw new InvalidOperationException("The provided node is not defined in this documentation.");
         }
+
+        var documentationReference = Source.ReferenceResolver.GetReference(Source, node);
+        
+        _references[node] = documentationReference;
+        
+        return documentationReference;
     }
-    
-    
+
     /// <summary>
     /// Initializes a new instance of the <see cref="MemberDocumentation"/> class.
     /// </summary>
@@ -61,20 +69,4 @@ protected MemberDocumentation(XDoc source, XmlNode? node)
         Source = source;
         Node = node;
     }
-
-    /// <summary>
-    /// Resolves the documentation.
-    /// </summary>
-    private void OnRequireResolve()
-    {
-        if (_isResolved)
-        {
-            return;
-        }
-
-        _inherited = InheritanceResolver.Resolve(this);
-        _references = CrefResolver.Resolve(this);
-
-        _isResolved = true;
-    }
 }

src/BitzArt.XDoc/Models/Cref.cs

@@ -0,0 +1,67 @@
+namespace BitzArt.XDoc;
+
+/// <summary>
+/// Represents a parsed C# XML documentation code reference (cref) attribute.
+/// Extracts and stores the type and member information from a cref string.
+/// </summary>
+public record Cref
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Cref"/> record by parsing the provided cref string.
+    /// </summary>
+    /// <param name="cref">The cref string to parse (e.g. "T:Namespace.Type" or "M:Namespace.Type.Method").</param>
+    public Cref(string cref)
+    {
+        Prefix = cref[..2];
+
+        var lastIndexOf = cref.LastIndexOf('.');
+
+        if (Prefix is "T:")
+        {
+            Type = cref.Substring(lastIndexOf + 1, cref.Length - lastIndexOf - 1);
+            Member = null;
+        }
+        else if (Prefix is "M:" or "P:" or "F:")
+        {
+            Type = cref.Substring(2, lastIndexOf - 2);
+            Member = cref.Substring(lastIndexOf + 1, cref.Length - lastIndexOf - 1);
+        }
+        else
+        {
+            throw new ArgumentException($"Invalid cref: {cref}");
+        }
+
+        var typeLastIndexOf = Type.LastIndexOf('.');
+
+        ShortType = Type.Substring(typeLastIndexOf + 1, Type.Length - typeLastIndexOf - 1);
+    }
+    
+    /// <summary>
+    /// The prefix of the cref (e.g. "T:", "M:", "P:", "F:").
+    /// </summary>
+    public string Prefix { get; init; }
+
+    /// <summary>
+    /// The type name
+    /// </summary>
+    public string Type { get; init; }
+
+    /// <summary>
+    /// The short type name (without namespace)
+    /// </summary>
+    public string ShortType { get; init; }
+
+    /// <summary>
+    /// Method, property, or field name if present in the cref.
+    /// Will be null for type references.
+    /// </summary>
+    public string? Member { get; init; }
+
+    /// <summary>
+    /// Returns a string that represents the current object.
+    /// </summary>
+    public override string ToString()
+    {
+        return $"{Prefix}{Type}{(Member != null ? "." + Member : string.Empty)}";
+    }
+}

src/BitzArt.XDoc/Models/DocumentationReference.cs

@@ -0,0 +1,37 @@
+using System.Xml;
+
+namespace BitzArt.XDoc;
+
+/// <summary>
+/// Represents a class for documentation references.
+/// </summary>
+public class DocumentationReference
+{
+    /// <summary>
+    /// Actual XML node that caused this requirement
+    /// </summary>
+    public XmlNode RequirementNode { get; private init; }
+
+    /// <summary>
+    /// The code reference that identifies the target element.
+    /// </summary>
+    public Cref? Cref { get; init; }
+
+    /// <summary>
+    /// Target member documentation
+    /// </summary>
+    public MemberDocumentation? Target { get; private init; }
+
+    /// <summary>
+    /// Default constructor
+    /// </summary>
+    /// <param name="requirementNode"></param>
+    /// <param name="target"></param>
+    /// <param name="cref"></param>
+    public DocumentationReference(XmlNode requirementNode, MemberDocumentation? target, string? cref)
+    {
+        Target = target;
+        RequirementNode = requirementNode;
+        Cref = string.IsNullOrWhiteSpace(cref) ? null : new Cref(cref);
+    }
+}

src/BitzArt.XDoc/Models/MemberDocumentationReference.cs

@@ -25,7 +25,7 @@ public abstract class TypeMemberDocumentation<TMember> : MemberDocumentation
     /// <summary>
     /// Name of the member.
     /// </summary>
-    internal string MemberName => _member.Name;
+    public string MemberName => _member.Name;
 
     internal TypeMemberDocumentation(XDoc source, TypeDocumentation declaringTypeDocumentation, TMember member, XmlNode node)
         : base(source, node)

src/BitzArt.XDoc/Models/Members/!TypeMemberDocumentation.cs

@@ -14,7 +14,7 @@ public sealed class TypeDocumentation : MemberDocumentation
     /// <summary>
     /// The <see cref="Type"/> this documentation if provided for.
     /// </summary>
-    internal Type Type { get; private init; }
+    public Type Type { get; private init; }
 
     /// <summary>
     /// List of members declared by this <see cref="Type"/>.

src/BitzArt.XDoc/Models/TypeDocumentation.cs

@@ -0,0 +1,24 @@
+using System.Xml;
+
+namespace BitzArt.XDoc;
+
+/// <summary>
+/// Resolves documentation references from XML nodes.
+/// </summary>
+/// <remarks>
+/// This interface is used to extract documentation references from XML documentation comments,
+/// such as cref links and inheritdoc elements, to create structured representation of code references.
+/// </remarks>
+public interface IDocumentationReferenceResolver
+{
+    /// <summary>
+    /// Extracts a documentation reference from the provided XML node.
+    /// </summary>
+    /// <param name="source"></param>
+    /// <param name="node">The XML node to extract the reference from.</param>
+    /// <returns>
+    /// A <see cref="DocumentationReference"/> object if a reference can be extracted;
+    /// otherwise, <see langword="null"/>.
+    /// </returns>
+    DocumentationReference? GetReference(XDoc source, XmlNode node);
+}