Add option ignored-title-parts (#975)

dotnet · Oct 31, 2022 · 395e45e · 395e45e
1 parent 77f4e4a
commit 395e45e
Show file tree

Hide file tree

Showing 9 changed files with 127 additions and 23 deletions.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [CLI] Generate reference documentation that can be published with Sphinx ([#961](https://github.com/josefpihrt/roslynator/pull/961)).
   - `roslynator generate-doc --host sphinx`
 - [CLI] Basic support for `<inheritdoc />` when generating documentation (`generate-doc` command) ([#972](https://github.com/josefpihrt/roslynator/pull/972)).
+- [CLI] Add option `ignored-title-parts` (`generate-doc` command) ([#975](https://github.com/josefpihrt/roslynator/pull/975)).
 
 ### Changed
 

diff --git a/src/CommandLine/Commands/GenerateDocCommand.cs b/src/CommandLine/Commands/GenerateDocCommand.cs
@@ -29,6 +29,7 @@ public GenerateDocCommand(
             TypeDocumentationParts ignoredTypeParts,
             MemberDocumentationParts ignoredMemberParts,
             CommonDocumentationParts ignoredCommonParts,
+            SymbolTitleParts ignoredTitleParts,
             OmitMemberParts omitMemberParts,
             IncludeContainingNamespaceFilter includeContainingNamespaceFilter,
             Visibility visibility,
@@ -46,6 +47,7 @@ public GenerateDocCommand(
             IgnoredMemberParts = ignoredMemberParts;
             IgnoredCommonParts = ignoredCommonParts;
             OmitMemberParts = omitMemberParts;
+            IgnoredTitleParts = ignoredTitleParts;
             IncludeContainingNamespaceFilter = includeContainingNamespaceFilter;
             Visibility = visibility;
             DocumentationHost = documentationHost;
@@ -70,6 +72,8 @@ public GenerateDocCommand(
 
         public OmitMemberParts OmitMemberParts { get; }
 
+        public SymbolTitleParts IgnoredTitleParts { get; }
+
         public IncludeContainingNamespaceFilter IncludeContainingNamespaceFilter { get; }
 
         public Visibility Visibility { get; }
@@ -111,6 +115,7 @@ public override async Task<CommandResult> ExecuteAsync(ProjectOrSolution project
                 ignoredTypeParts: IgnoredTypeParts,
                 ignoredMemberParts: IgnoredMemberParts,
                 ignoredCommonParts: IgnoredCommonParts,
+                ignoredTitleParts: IgnoredTitleParts,
                 includeContainingNamespaceFilter: IncludeContainingNamespaceFilter,
                 filesLayout: FilesLayout,
                 scrollToContent: (DocumentationHost == DocumentationHost.GitHub) && Options.ScrollToContent);

diff --git a/src/CommandLine/OptionNames.cs b/src/CommandLine/OptionNames.cs
@@ -20,6 +20,7 @@ internal static class OptionNames
         public const string IgnoredProjects = "ignored-projects";
         public const string IgnoredRootParts = "ignored-root-parts";
         public const string IgnoredScope = "ignored-scope";
+        public const string IgnoredTitleParts = "ignored-title-parts";
         public const string IgnoredTypeParts = "ignored-type-parts";
         public const string IncludeContainingNamespace = "include-containing-namespace";
         public const string IncludeSystemNamespace = "include-system-namespace";

diff --git a/src/CommandLine/Options/GenerateDocCommandLineOptions.cs b/src/CommandLine/Options/GenerateDocCommandLineOptions.cs
@@ -2,7 +2,6 @@
 
 using System.Collections.Generic;
 using CommandLine;
-using Roslynator.Documentation;
 using static Roslynator.Documentation.DocumentationOptions;
 
 namespace Roslynator.CommandLine
@@ -45,6 +44,12 @@ public class GenerateDocCommandLineOptions : AbstractGenerateDocCommandLineOptio
             MetaValue = "<IGNORED_ROOT_PARTS>")]
         public IEnumerable<string> IgnoredRootParts { get; set; }
 
+        [Option(
+            longName: OptionNames.IgnoredTitleParts,
+            HelpText = "Defines title parts of a documentation that should be excluded. Allowed value is containing-namespace, containing-type, parameters and explicit-implementation.",
+            MetaValue = "<IGNORED_TITLE_PARTS>")]
+        public IEnumerable<string> IgnoredTitleParts { get; set; }
+
         [Option(
             longName: OptionNames.IgnoredTypeParts,
             HelpText = "Defines parts of a type documentation that should be excluded. Allowed values are content, containing-namespace, containing-assembly, obsolete-message, summary, declaration, type-parameters, parameters, return-value, inheritance, attributes, derived, implements, examples, remarks, constructors, fields, indexers, properties, methods, operators, events, explicit-interface-implementations, extension-methods, classes, structs, interfaces, enums, delegates and see-also.",

diff --git a/src/CommandLine/Program.cs b/src/CommandLine/Program.cs
@@ -762,6 +762,9 @@ private static async Task<int> GenerateDocAsync(GenerateDocCommandLineOptions op
             if (!TryParseOptionValueAsEnumFlags(options.IgnoredCommonParts, OptionNames.IgnoredCommonParts, out CommonDocumentationParts ignoredCommonParts, DocumentationOptions.DefaultValues.IgnoredCommonParts))
                 return ExitCodes.Error;
 
+            if (!TryParseOptionValueAsEnumFlags(options.IgnoredTitleParts, OptionNames.IgnoredTitleParts, out SymbolTitleParts ignoredTitleParts, DocumentationOptions.DefaultValues.IgnoredTitleParts))
+                return ExitCodes.Error;
+
             if (!TryParseOptionValueAsEnumFlags(options.IncludeContainingNamespace, OptionNames.IncludeContainingNamespace, out IncludeContainingNamespaceFilter includeContainingNamespaceFilter, DocumentationOptions.DefaultValues.IncludeContainingNamespaceFilter))
                 return ExitCodes.Error;
 
@@ -784,21 +787,22 @@ private static async Task<int> GenerateDocAsync(GenerateDocCommandLineOptions op
                 return ExitCodes.Error;
 
             var command = new GenerateDocCommand(
-                options,
-                depth,
-                ignoredRootParts,
-                ignoredNamespaceParts,
-                ignoredTypeParts,
-                ignoredMemberParts,
-                ignoredCommonParts,
-                omitMemberParts,
-                includeContainingNamespaceFilter,
-                visibility,
-                documentationHost,
-                filesLayout,
+                options: options,
+                depth: depth,
+                ignoredRootParts: ignoredRootParts,
+                ignoredNamespaceParts: ignoredNamespaceParts,
+                ignoredTypeParts: ignoredTypeParts,
+                ignoredMemberParts: ignoredMemberParts,
+                ignoredCommonParts: ignoredCommonParts,
+                ignoredTitleParts: ignoredTitleParts,
+                omitMemberParts: omitMemberParts,
+                includeContainingNamespaceFilter: includeContainingNamespaceFilter,
+                visibility: visibility,
+                documentationHost: documentationHost,
+                filesLayout: filesLayout,
                 groupByCommonNamespace: options.GroupByCommonNamespace,
                 inheritanceStyle: inheritanceStyle,
-                projectFilter);
+                projectFilter: projectFilter);
 
             CommandStatus status = await command.ExecuteAsync(paths, options.MSBuildPath, options.Properties);
 

diff --git a/src/Documentation/DocumentationGenerator.cs b/src/Documentation/DocumentationGenerator.cs
@@ -332,7 +332,14 @@ private DocumentationGeneratorResult GenerateNamespace(INamespaceSymbol namespac
 
                 SymbolXmlDocumentation xmlDocumentation = DocumentationModel.GetXmlDocumentation(namespaceSymbol, Options.PreferredCultureName);
 
-                writer.WriteHeading(1, namespaceSymbol, TypeSymbolDisplayFormats.Name_ContainingTypes_Namespaces, addLink: false, linkDestination: (Options.ScrollToContent) ? WellKnownNames.TopFragmentName : null);
+                writer.WriteHeading(
+                    1,
+                    namespaceSymbol,
+                    ((Options.IgnoredTitleParts & SymbolTitleParts.ContainingNamespace) != 0)
+                        ? TypeSymbolDisplayFormats.Name
+                        : TypeSymbolDisplayFormats.Name_ContainingTypes_Namespaces,
+                    addLink: false,
+                    linkDestination: (Options.ScrollToContent) ? WellKnownNames.TopFragmentName : null);
 
                 foreach (NamespaceDocumentationParts part in EnabledAndSortedNamespaceParts)
                 {
@@ -591,7 +598,9 @@ private DocumentationGeneratorResult GenerateType(TypeDocumentationModel typeMod
                 writer.WriteHeading(
                     1,
                     typeSymbol,
-                    TypeSymbolDisplayFormats.Name_ContainingTypes_TypeParameters,
+                    ((Options.IgnoredTitleParts & SymbolTitleParts.ContainingType) != 0)
+                            ? TypeSymbolDisplayFormats.Name_TypeParameters
+                            : TypeSymbolDisplayFormats.Name_ContainingTypes_TypeParameters,
                     SymbolDisplayAdditionalMemberOptions.UseItemPropertyName | SymbolDisplayAdditionalMemberOptions.UseOperatorName,
                     addLink: false,
                     linkDestination: (Options.ScrollToContent) ? WellKnownNames.TopFragmentName : null);

diff --git a/src/Documentation/DocumentationOptions.cs b/src/Documentation/DocumentationOptions.cs
@@ -39,6 +39,7 @@ public DocumentationOptions(
             TypeDocumentationParts ignoredTypeParts = TypeDocumentationParts.None,
             MemberDocumentationParts ignoredMemberParts = MemberDocumentationParts.None,
             CommonDocumentationParts ignoredCommonParts = CommonDocumentationParts.None,
+            SymbolTitleParts ignoredTitleParts = SymbolTitleParts.None,
             IncludeContainingNamespaceFilter includeContainingNamespaceFilter = IncludeContainingNamespaceFilter.None,
             FilesLayout filesLayout = FilesLayout.Hierarchical,
             bool scrollToContent = DefaultValues.ScrollToContent)
@@ -74,6 +75,7 @@ public DocumentationOptions(
             IgnoredTypeParts = ignoredTypeParts;
             IgnoredMemberParts = ignoredMemberParts;
             IgnoredCommonParts = ignoredCommonParts;
+            IgnoredTitleParts = ignoredTitleParts;
             IncludeContainingNamespaceFilter = includeContainingNamespaceFilter;
             FilesLayout = filesLayout;
             ScrollToContent = scrollToContent;
@@ -141,6 +143,8 @@ public DocumentationOptions(
 
         public CommonDocumentationParts IgnoredCommonParts { get; }
 
+        public SymbolTitleParts IgnoredTitleParts { get; }
+
         public IncludeContainingNamespaceFilter IncludeContainingNamespaceFilter { get; }
 
         public FilesLayout FilesLayout { get; }
@@ -202,6 +206,7 @@ internal static class DefaultValues
             public const TypeDocumentationParts IgnoredTypeParts = TypeDocumentationParts.None;
             public const MemberDocumentationParts IgnoredMemberParts = MemberDocumentationParts.None;
             public const CommonDocumentationParts IgnoredCommonParts = CommonDocumentationParts.None;
+            public const SymbolTitleParts IgnoredTitleParts = SymbolTitleParts.None;
             public const IncludeContainingNamespaceFilter IncludeContainingNamespaceFilter = Roslynator.Documentation.IncludeContainingNamespaceFilter.None;
         }
     }

diff --git a/src/Documentation/DocumentationWriter.cs b/src/Documentation/DocumentationWriter.cs
@@ -18,6 +18,10 @@ public abstract class DocumentationWriter : IDisposable
     {
         private bool _disposed;
 
+        private SymbolDisplayFormat _nonOverloadedConstructorDisplayFormat;
+        private SymbolDisplayFormat _nonOverloadedMemberDisplayFormat;
+        private SymbolDisplayFormat _overloadedMemberDisplayFormat;
+
         protected DocumentationWriter(DocumentationContext context)
         {
             Context = context ?? throw new ArgumentNullException(nameof(context));
@@ -350,27 +354,81 @@ internal void WriteMemberTitle(ISymbol symbol, bool isOverloaded)
         {
             WriteStartHeading(1);
 
-            if (symbol.Kind == SymbolKind.Method
-                && ((IMethodSymbol)symbol).MethodKind == MethodKind.Constructor)
+            if ((symbol as IMethodSymbol)?.MethodKind == MethodKind.Constructor)
             {
                 if (isOverloaded)
                 {
-                    WriteString(symbol.ContainingType.ToDisplayString(TypeSymbolDisplayFormats.Name_ContainingTypes_TypeParameters));
+                    SymbolDisplayFormat format = ((Options.IgnoredTitleParts & SymbolTitleParts.ContainingType) != 0)
+                        ? TypeSymbolDisplayFormats.Name_TypeParameters
+                        : TypeSymbolDisplayFormats.Name_ContainingTypes_TypeParameters;
+
+                    WriteString(symbol.ContainingType.ToDisplayString(format));
                     WriteSpace();
                     WriteString(Resources.ConstructorsTitle);
                 }
                 else
                 {
-                    WriteString(symbol.ToDisplayString(DocumentationDisplayFormats.SimpleDeclaration));
+                    _nonOverloadedConstructorDisplayFormat ??= DocumentationDisplayFormats.Default.Update(
+                        genericsOptions: SymbolDisplayGenericsOptions.IncludeTypeParameters,
+                        memberOptions: ((Options.IgnoredTitleParts & SymbolTitleParts.Parameters) != 0)
+                            ? SymbolDisplayMemberOptions.None
+                            : SymbolDisplayMemberOptions.IncludeParameters,
+                        parameterOptions: SymbolDisplayParameterOptions.IncludeType);
+
+                    if ((Options.IgnoredTitleParts & SymbolTitleParts.ContainingType) == 0)
+                    {
+                        INamedTypeSymbol containingType = symbol.ContainingType.ContainingType;
+
+                        if (containingType is not null)
+                        {
+                            WriteString(containingType.ToDisplayString(TypeSymbolDisplayFormats.Name_ContainingTypes_TypeParameters));
+                            WriteString(".");
+                        }
+                    }
+
+                    WriteString(symbol.ToDisplayString(_nonOverloadedConstructorDisplayFormat));
                     WriteSpace();
                     WriteString(Resources.ConstructorTitle);
                 }
             }
             else
             {
-                SymbolDisplayFormat format = (isOverloaded)
-                    ? DocumentationDisplayFormats.OverloadedMemberTitle
-                    : DocumentationDisplayFormats.MemberTitle;
+                SymbolDisplayFormat format;
+                if (isOverloaded)
+                {
+                    _overloadedMemberDisplayFormat ??= DocumentationDisplayFormats.Default.Update(
+                        typeQualificationStyle: SymbolDisplayTypeQualificationStyle.NameAndContainingTypes,
+                        genericsOptions: SymbolDisplayGenericsOptions.None,
+                        memberOptions: (((Options.IgnoredTitleParts & SymbolTitleParts.ExplicitImplementation) != 0)
+                                ? SymbolDisplayMemberOptions.None
+                                : SymbolDisplayMemberOptions.IncludeExplicitInterface)
+                            | (((Options.IgnoredTitleParts & SymbolTitleParts.ContainingType) != 0)
+                                ? SymbolDisplayMemberOptions.None
+                                : SymbolDisplayMemberOptions.IncludeContainingType));
+
+                    format = _overloadedMemberDisplayFormat;
+                }
+                else
+                {
+                    _nonOverloadedMemberDisplayFormat ??= DocumentationDisplayFormats.Default.Update(
+                        typeQualificationStyle: SymbolDisplayTypeQualificationStyle.NameAndContainingTypes,
+                        genericsOptions: SymbolDisplayGenericsOptions.IncludeTypeParameters,
+                        memberOptions: (((Options.IgnoredTitleParts & SymbolTitleParts.ExplicitImplementation) != 0)
+                            ? SymbolDisplayMemberOptions.None
+                            : SymbolDisplayMemberOptions.IncludeExplicitInterface)
+                            | (((Options.IgnoredTitleParts & SymbolTitleParts.Parameters) != 0)
+                                ? SymbolDisplayMemberOptions.None
+                                : SymbolDisplayMemberOptions.IncludeParameters)
+                            | (((Options.IgnoredTitleParts & SymbolTitleParts.ContainingType) != 0)
+                                ? SymbolDisplayMemberOptions.None
+                                : SymbolDisplayMemberOptions.IncludeContainingType),
+                        delegateStyle: ((Options.IgnoredTitleParts & SymbolTitleParts.Parameters) != 0)
+                            ? SymbolDisplayDelegateStyle.NameOnly
+                            : SymbolDisplayDelegateStyle.NameAndParameters,
+                        parameterOptions: SymbolDisplayParameterOptions.IncludeType);
+
+                    format = _nonOverloadedMemberDisplayFormat;
+                }
 
                 WriteString(symbol.ToDisplayString(format, SymbolDisplayAdditionalMemberOptions.UseItemPropertyName | SymbolDisplayAdditionalMemberOptions.UseOperatorName));
                 WriteSpace();

diff --git a/src/Documentation/SymbolTitleParts.cs b/src/Documentation/SymbolTitleParts.cs
@@ -0,0 +1,16 @@
+// Copyright (c) Josef Pihrt and Contributors. Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+
+namespace Roslynator.Documentation
+{
+    [Flags]
+    public enum SymbolTitleParts
+    {
+        None = 0,
+        ContainingNamespace = 1,
+        ContainingType = 1 << 1,
+        Parameters = 1 << 2,
+        ExplicitImplementation = 1 << 3,
+    }
+}