Fixes #75: Improves inheritdoc so that developer documentation is pro…

…perly referenced on the autogenerated interfaces
codecentric · Nov 4, 2024 · 8728df6 · 8728df6
1 parent f30a718
commit 8728df6
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 71 deletions.
diff --git a/AutomaticInterface/AutomaticInterface/Builder.cs b/AutomaticInterface/AutomaticInterface/Builder.cs
@@ -9,13 +9,13 @@ namespace AutomaticInterface;
 
 public static class Builder
 {
-    private const string InheritDoc = "/// <inheritdoc />"; // we use inherit doc because that should be able to fetch documentation from base classes.
+    private static string InheritDoc(string source) => $"/// <inheritdoc cref=\"{source}\" />"; // we use inherit doc because that should be able to fetch documentation from base classes.
 
     private static readonly SymbolDisplayFormat MethodSignatureDisplayFormat =
         new(
             memberOptions: SymbolDisplayMemberOptions.IncludeParameters,
             parameterOptions: SymbolDisplayParameterOptions.IncludeType
-                | SymbolDisplayParameterOptions.IncludeParamsRefOut
+                              | SymbolDisplayParameterOptions.IncludeParamsRefOut
         );
 
     private static readonly SymbolDisplayFormat TypeDisplayFormat =
@@ -24,7 +24,7 @@ public static class Builder
             typeQualificationStyle: SymbolDisplayTypeQualificationStyle.NameAndContainingTypesAndNamespaces,
             genericsOptions: SymbolDisplayGenericsOptions.IncludeTypeParameters,
             miscellaneousOptions: SymbolDisplayMiscellaneousOptions.UseSpecialTypes
-                | SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier
+                                  | SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier
         );
 
     public static string BuildInterfaceFor(ITypeSymbol typeSymbol)
@@ -67,6 +67,7 @@ private static string GetNameSpace(ISymbol typeSymbol)
         {
             return typeSymbol.ContainingNamespace.ToDisplayString();
         }
+
         var customNs = generationAttribute.ConstructorArguments.FirstOrDefault().Value?.ToString();
 
         return string.IsNullOrWhiteSpace(customNs)
@@ -92,10 +93,7 @@ InterfaceBuilder codeGenerator
             .GroupBy(x => x.ToDisplayString(MethodSignatureDisplayFormat))
             .Select(g => g.First())
             .ToList()
-            .ForEach(method =>
-            {
-                AddMethod(codeGenerator, method);
-            });
+            .ForEach(method => { AddMethod(codeGenerator, method); });
     }
 
     private static void AddMethod(InterfaceBuilder codeGenerator, IMethodSymbol method)
@@ -117,7 +115,7 @@ private static void AddMethod(InterfaceBuilder codeGenerator, IMethodSymbol meth
         codeGenerator.AddMethodToInterface(
             name,
             returnType.ToDisplayString(TypeDisplayFormat),
-            InheritDoc,
+            InheritDoc(method.ToDisplayString()),
             paramResult,
             typedArgs
         );
@@ -197,7 +195,7 @@ InterfaceBuilder codeGenerator
                 codeGenerator.AddEventToInterface(
                     name,
                     type.ToDisplayString(TypeDisplayFormat),
-                    InheritDoc
+                    InheritDoc(evt.ToDisplayString())
                 );
             });
     }
@@ -285,7 +283,7 @@ InterfaceBuilder interfaceGenerator
                     hasGet,
                     hasSet,
                     isRef,
-                    InheritDoc
+                    InheritDoc(prop.ToDisplayString())
                 );
             });
     }
@@ -351,4 +349,4 @@ private static string GetGeneric(TypeDeclarationSyntax classSyntax)
 
         return formattedGeneric;
     }
-}
+}
diff --git a/AutomaticInterface/AutomaticInterfaceExample/DemoClassWithCustomNamespace.cs b/AutomaticInterface/AutomaticInterfaceExample/DemoClassWithCustomNamespace.cs
@@ -15,6 +15,11 @@ namespace AutomaticInterfaceExample
     )]
     public class DemoClass2 : IDemoClass2
     {
-        public void Test() { }
+        /// <summary>
+        /// This is a test method
+        /// </summary>
+        public void Test()
+        {
+        }
     }
-}
+}
diff --git a/AutomaticInterface/Tests/GeneratorTests.Properties.cs b/AutomaticInterface/Tests/GeneratorTests.Properties.cs
@@ -39,7 +39,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; }
 
                 }
@@ -85,7 +85,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; }
 
                 }
@@ -139,7 +139,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.NullableProperty" />
                     string? NullableProperty { get; set; }
 
                 }
@@ -195,7 +195,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.NullableProperty" />
                     global::System.Threading.Tasks.Task<string?> NullableProperty { get; set; }
 
                 }
@@ -243,7 +243,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface ISecondClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.SecondClass.AProperty" />
                     int AProperty { get; set; }
 
                 }
@@ -288,7 +288,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.SomeProperty" />
                     string SomeProperty { get; set; }
 
                 }
@@ -334,7 +334,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.SomeProperty" />
                     string SomeProperty { get; set; }
 
                 }
@@ -377,7 +377,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; set; }
 
                 }
@@ -421,7 +421,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { set; }
 
                 }
@@ -465,7 +465,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; }
 
                 }
@@ -508,7 +508,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; init; }
 
                 }

diff --git a/AutomaticInterface/Tests/GeneratorTests.TypeResolution.cs b/AutomaticInterface/Tests/GeneratorTests.TypeResolution.cs
@@ -35,7 +35,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; set; }
 
                 }
@@ -77,7 +77,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     string Hello { get; set; }
 
                 }
@@ -120,7 +120,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.Hello" />
                     global::System.Threading.Tasks.Task Hello { get; set; }
 
                 }
@@ -169,10 +169,10 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IModelManager
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.ModelManager.GetModel1()" />
                     global::AutomaticInterfaceExample.Models1.Model GetModel1();
 
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.ModelManager.GetModel2()" />
                     global::AutomaticInterfaceExample.Models2.Model GetModel2();
 
                 }
@@ -222,7 +222,7 @@ namespace RootNamespace.ModelManager
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IModelManager
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="RootNamespace.ModelManager.ModelManager.GetModel()" />
                     global::RootNamespace.Models.Model GetModel();
 
                 }
@@ -268,7 +268,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.GetTask()" />
                     global::System.Threading.Tasks.Task GetTask();
 
                 }
@@ -314,7 +314,7 @@ namespace AutomaticInterfaceExample
                 [global::System.CodeDom.Compiler.GeneratedCode("AutomaticInterface", "")]
                 public partial interface IDemoClass
                 {
-                    /// <inheritdoc />
+                    /// <inheritdoc cref="AutomaticInterfaceExample.DemoClass.GetClass()" />
                     global::GlobalNamespace.AClass GetClass();
 
                 }