consistent member xml documentation

DavidVollmers · Jun 22, 2024 · 3361347 · 3361347
1 parent 1a6998a
commit 3361347
Show file tree

Hide file tree

Showing 4 changed files with 86 additions and 80 deletions.
diff --git a/src/Doki.Abstractions/MemberDocumentation.cs b/src/Doki.Abstractions/MemberDocumentation.cs
@@ -1,4 +1,5 @@
-namespace Doki;
+// ReSharper disable InconsistentNaming
+namespace Doki;
 
 /// <summary>
 /// Represents the documentation for a member.
@@ -20,10 +21,38 @@ public record MemberDocumentation : DocumentationObject
     /// </summary>
     public string? Assembly { get; init; }
 
+    internal XmlDocumentation[] InternalSummaries = [];
+
     /// <summary>
     /// Gets the summary of the member.
     /// </summary>
-    public XmlDocumentation? Summary { get; set; }
+    public XmlDocumentation[] Summaries
+    {
+        get => InternalSummaries;
+        init => InternalSummaries = value;
+    }
+
+    internal XmlDocumentation[] InternalExamples = [];
+
+    /// <summary>
+    /// Get the examples of the member.
+    /// </summary>
+    public XmlDocumentation[] Examples
+    {
+        get => InternalExamples;
+        init => InternalExamples = value;
+    }
+
+    internal XmlDocumentation[] InternalRemarks = [];
+
+    /// <summary>
+    /// Gets the remarks of the member.
+    /// </summary>
+    public XmlDocumentation[] Remarks
+    {
+        get => InternalRemarks;
+        init => InternalRemarks = value;
+    }
 
     /// <summary>
     /// Gets a value indicating whether the type is documented.

diff --git a/src/Doki.Abstractions/TypeDocumentation.cs b/src/Doki.Abstractions/TypeDocumentation.cs
@@ -10,28 +10,6 @@ public sealed record TypeDocumentation : TypeDocumentationReference
     /// </summary>
     public string Definition { get; init; } = null!;
 
-    internal XmlDocumentation[] InternalExamples = [];
-
-    /// <summary>
-    /// Get the examples of the type.
-    /// </summary>
-    public XmlDocumentation[] Examples
-    {
-        get => InternalExamples;
-        init => InternalExamples = value;
-    }
-
-    internal XmlDocumentation[] InternalRemarks = [];
-
-    /// <summary>
-    /// Gets the remarks of the type.
-    /// </summary>
-    public XmlDocumentation[] Remarks
-    {
-        get => InternalRemarks;
-        init => InternalRemarks = value;
-    }
-
     internal TypeDocumentationReference[] InternalInterfaces = [];
 
     /// <summary>

diff --git a/src/Doki/DocumentationGenerator.Content.cs b/src/Doki/DocumentationGenerator.Content.cs
@@ -39,10 +39,6 @@ private IEnumerable<GenericTypeArgumentDocumentation> BuildGenericTypeArgumentDo
             logger.LogDebug("Generating documentation for generic argument {GenericArgument}.", genericArgumentId);
 
             var description = typeXml?.SelectSingleNode($"typeparam[@name='{genericArgumentId}']");
-            if (description == null && typeXml != null)
-            {
-                logger.LogWarning("No description found for generic argument {GenericArgument}.", genericArgument);
-            }
 
             var genericArgumentAssembly = genericArgument.Assembly.GetName();
 
@@ -60,14 +56,17 @@ private IEnumerable<GenericTypeArgumentDocumentation> BuildGenericTypeArgumentDo
                 Parent = parent,
             };
 
-            if (genericArgument.BaseType != null)
-                genericArgumentDocumentation.InternalBaseType =
-                    BuildTypeDocumentationReference(genericArgument.BaseType, genericArgumentDocumentation);
-
             if (description != null)
                 genericArgumentDocumentation.Description =
                     BuildXmlDocumentation(description, genericArgumentDocumentation);
 
+            SetInternalTypeDocumentationReferenceProperties(genericArgumentDocumentation, genericArgument, null);
+
+            if (genericArgumentDocumentation.Description == null)
+            {
+                logger.LogWarning("No description found for generic argument {GenericArgument}.", genericArgument);
+            }
+
             yield return genericArgumentDocumentation;
         }
     }
@@ -116,12 +115,6 @@ private IEnumerable<MemberDocumentation> BuildFieldDocumentation(Type type, Docu
 
             var memberXml = assemblyXml?.SelectSingleNode($"//doc//members//member[@name='F:{fieldId}']");
 
-            var summary = memberXml?.SelectSingleNode("summary");
-            if (summary == null)
-            {
-                logger.LogWarning("No summary found for field {Field}.", fieldId);
-            }
-
             var fieldAssembly = field.DeclaringType!.Assembly.GetName();
 
             var fieldDocumentation = new MemberDocumentation
@@ -135,8 +128,12 @@ private IEnumerable<MemberDocumentation> BuildFieldDocumentation(Type type, Docu
                 IsDocumented = true
             };
 
-            if (summary != null)
-                fieldDocumentation.Summary = BuildXmlDocumentation(summary, fieldDocumentation);
+            SetInternalMemberDocumentationProperties(fieldDocumentation, memberXml);
+
+            if (fieldDocumentation.Summaries.Length == 0)
+            {
+                logger.LogWarning("No summary found for field {Field}.", fieldId);
+            }
 
             yield return fieldDocumentation;
         }
@@ -158,12 +155,6 @@ private IEnumerable<MemberDocumentation> BuildConstructorDocumentation(Type type
 
             var memberXml = assemblyXml?.SelectSingleNode($"//doc//members//member[@name='M:{constructorId}']");
 
-            var summary = memberXml?.SelectSingleNode("summary");
-            if (summary == null)
-            {
-                logger.LogWarning("No summary found for constructor {Constructor}.", constructorId);
-            }
-
             var constructorAssembly = constructor.DeclaringType!.Assembly.GetName();
 
             var constructorDocumentation = new MemberDocumentation
@@ -177,8 +168,12 @@ private IEnumerable<MemberDocumentation> BuildConstructorDocumentation(Type type
                 IsDocumented = true
             };
 
-            if (summary != null)
-                constructorDocumentation.Summary = BuildXmlDocumentation(summary, constructorDocumentation);
+            SetInternalMemberDocumentationProperties(constructorDocumentation, memberXml);
+
+            if (constructorDocumentation.Summaries.Length == 0)
+            {
+                logger.LogWarning("No summary found for constructor {Constructor}.", constructorId);
+            }
 
             yield return constructorDocumentation;
         }
@@ -200,12 +195,6 @@ private IEnumerable<MemberDocumentation> BuildPropertyDocumentation(Type type, D
 
             var memberXml = assemblyXml?.SelectSingleNode($"//doc//members//member[@name='P:{propertyId}']");
 
-            var summary = memberXml?.SelectSingleNode("summary");
-            if (summary == null)
-            {
-                logger.LogWarning("No summary found for property {Property}.", propertyId);
-            }
-
             var propertyAssembly = property.DeclaringType!.Assembly.GetName();
 
             var propertyDocumentation = new MemberDocumentation
@@ -219,8 +208,12 @@ private IEnumerable<MemberDocumentation> BuildPropertyDocumentation(Type type, D
                 IsDocumented = true
             };
 
-            if (summary != null)
-                propertyDocumentation.Summary = BuildXmlDocumentation(summary, propertyDocumentation);
+            SetInternalMemberDocumentationProperties(propertyDocumentation, memberXml);
+
+            if (propertyDocumentation.Summaries.Length == 0)
+            {
+                logger.LogWarning("No summary found for property {Property}.", propertyId);
+            }
 
             yield return propertyDocumentation;
         }
@@ -244,12 +237,6 @@ private IEnumerable<MemberDocumentation> BuildMethodDocumentation(Type type, Doc
 
             var memberXml = assemblyXml?.SelectSingleNode($"//doc//members//member[@name='M:{methodId}']");
 
-            var summary = memberXml?.SelectSingleNode("summary");
-            if (summary == null)
-            {
-                logger.LogWarning("No summary found for method {Method}.", methodId);
-            }
-
             var methodAssembly = method.DeclaringType!.Assembly.GetName();
 
             var methodDocumentation = new MemberDocumentation
@@ -263,8 +250,12 @@ private IEnumerable<MemberDocumentation> BuildMethodDocumentation(Type type, Doc
                 IsDocumented = true
             };
 
-            if (summary != null)
-                methodDocumentation.Summary = BuildXmlDocumentation(summary, methodDocumentation);
+            SetInternalMemberDocumentationProperties(methodDocumentation, memberXml);
+
+            if (methodDocumentation.Summaries.Length == 0)
+            {
+                logger.LogWarning("No summary found for method {Method}.", methodId);
+            }
 
             yield return methodDocumentation;
         }
@@ -487,10 +478,27 @@ private TypeDocumentationReference BuildTypeDocumentationReference(Type type, Do
             Parent = parent
         };
 
+        SetInternalTypeDocumentationReferenceProperties(typeDocumentationReference, type, null);
+
+        return typeDocumentationReference;
+    }
+
+    private void SetInternalTypeDocumentationReferenceProperties(TypeDocumentationReference typeDocumentationReference,
+        Type type, XPathNavigator? xml)
+    {
         if (type.BaseType != null)
             typeDocumentationReference.InternalBaseType =
                 BuildTypeDocumentationReference(type.BaseType, typeDocumentationReference);
 
-        return typeDocumentationReference;
+        SetInternalMemberDocumentationProperties(typeDocumentationReference, xml);
+    }
+
+    private void SetInternalMemberDocumentationProperties(MemberDocumentation memberDocumentation, XPathNavigator? xml)
+    {
+        memberDocumentation.InternalSummaries = BuildXmlDocumentation("summary", xml, memberDocumentation).ToArray();
+
+        memberDocumentation.InternalExamples = BuildXmlDocumentation("example", xml, memberDocumentation).ToArray();
+
+        memberDocumentation.InternalRemarks = BuildXmlDocumentation("remarks", xml, memberDocumentation).ToArray();
     }
 }
diff --git a/src/Doki/DocumentationGenerator.cs b/src/Doki/DocumentationGenerator.cs
@@ -320,12 +320,6 @@ private async Task<TypeDocumentation> GenerateTypeDocumentationAsync(GeneratorCo
 
         var typeXml = assemblyXml.SelectSingleNode($"//doc//members//member[@name='T:{typeId}']");
 
-        var summary = typeXml?.SelectSingleNode("summary");
-        if (summary == null)
-        {
-            context.Logger.LogWarning("No summary found for type {Type}.", typeId);
-        }
-
         var typeDocumentation = new TypeDocumentation
         {
             Id = typeId,
@@ -348,8 +342,6 @@ private async Task<TypeDocumentation> GenerateTypeDocumentationAsync(GeneratorCo
             IsGeneric = context.Current.IsGenericType,
         };
 
-        if (summary != null) typeDocumentation.Summary = BuildXmlDocumentation(summary, typeDocumentation);
-
         typeDocumentation.InternalGenericArguments =
             BuildGenericTypeArgumentDocumentation(context.Current, typeDocumentation, typeXml, context.Logger)
                 .ToArray();
@@ -360,10 +352,6 @@ private async Task<TypeDocumentation> GenerateTypeDocumentationAsync(GeneratorCo
         typeDocumentation.InternalDerivedTypes =
             BuildDerivedTypeDocumentation(context.Current, typeDocumentation).ToArray();
 
-        typeDocumentation.InternalExamples = BuildXmlDocumentation("example", typeXml, typeDocumentation).ToArray();
-
-        typeDocumentation.InternalRemarks = BuildXmlDocumentation("remarks", typeXml, typeDocumentation).ToArray();
-
         typeDocumentation.InternalConstructors =
             BuildConstructorDocumentation(context.Current, typeDocumentation, assemblyXml, context.Logger).ToArray();
 
@@ -376,9 +364,12 @@ private async Task<TypeDocumentation> GenerateTypeDocumentationAsync(GeneratorCo
         typeDocumentation.InternalMethods =
             BuildMethodDocumentation(context.Current, typeDocumentation, assemblyXml, context.Logger).ToArray();
 
-        if (context.Current.BaseType != null)
-            typeDocumentation.InternalBaseType =
-                BuildTypeDocumentationReference(context.Current.BaseType, typeDocumentation);
+        SetInternalTypeDocumentationReferenceProperties(typeDocumentation, context.Current, typeXml);
+
+        if (typeDocumentation.Summaries.Length == 0)
+        {
+            context.Logger.LogWarning("No summary found for type {Type}.", typeId);
+        }
 
         foreach (var output in context.Outputs)
         {