diff --git a/README.md b/README.md index 45bc8cc..c05d4cd 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,24 @@ To double check which configuration is being used, invoke dotnet document config ``` +If you wish to exclude private members, properties, or methods modify your configuration file like: + +```yaml +class: + ... + exclude_private: true +method: + ... + exclude_private: true +property: + ... + exclude_private: true +default_member: + ... + exclude_private: true + +``` + > 👉 Folder based configuration discovery is not yet supported ## Acknowledgments diff --git a/src/DotnetDocument.Tools/Handlers/ApplyDocumentHandler.cs b/src/DotnetDocument.Tools/Handlers/ApplyDocumentHandler.cs index 7078de2..46fc5ee 100644 --- a/src/DotnetDocument.Tools/Handlers/ApplyDocumentHandler.cs +++ b/src/DotnetDocument.Tools/Handlers/ApplyDocumentHandler.cs @@ -110,10 +110,17 @@ public Result Apply(string? path, bool isDryRun) // Replace the var changedSyntaxTree = root.ReplaceNodes(_walker.NodesWithoutXmlDoc, - (node, syntaxNode) => _serviceResolver - .Resolve(syntaxNode.Kind().ToString()) - ? - .Apply(syntaxNode) ?? syntaxNode); + (node, syntaxNode) => + { + var strategy = _serviceResolver.Resolve(syntaxNode.Kind().ToString()); + + if (strategy != null && strategy.ShouldDocument(syntaxNode)) + { + return strategy.Apply(syntaxNode); + } + + return syntaxNode; + }); // TODO: Don't write if no changes @@ -164,14 +171,24 @@ private IEnumerable GetFileDocumentationStatus(string foreach (var node in _walker.NodesWithoutXmlDoc) { - var nodeWithDoc = _serviceResolver - .Resolve(node.Kind().ToString()) - ? - .Apply(node); - - yield return new MemberDocumentationStatus(filePath, SyntaxUtils.FindMemberIdentifier(node), - node.Kind(), false, node, nodeWithDoc, - node.GetLocation().GetLineSpan().StartLinePosition.ToString()); + var docStrategy = _serviceResolver.Resolve(node.Kind().ToString()); + var shouldDocument = docStrategy?.ShouldDocument(node); + + // Check if we should document the node + if (shouldDocument.HasValue && shouldDocument.Value) + { + var nodeWithDoc = docStrategy?.Apply(node); + + yield return new MemberDocumentationStatus(filePath, SyntaxUtils.FindMemberIdentifier(node), + node.Kind(), false, node, nodeWithDoc, + node.GetLocation().GetLineSpan().StartLinePosition.ToString()); + } + else + { + yield return new MemberDocumentationStatus(filePath, SyntaxUtils.FindMemberIdentifier(node), + node.Kind(), true, null, node, + node.GetLocation().GetLineSpan().StartLinePosition.ToString()); + } } } diff --git a/src/DotnetDocument/Configuration/DocumentationOptions.cs b/src/DotnetDocument/Configuration/DocumentationOptions.cs index 67a3f02..4574037 100644 --- a/src/DotnetDocument/Configuration/DocumentationOptions.cs +++ b/src/DotnetDocument/Configuration/DocumentationOptions.cs @@ -18,6 +18,19 @@ public abstract class MemberDocumentationOptionsBase /// public bool Required { get; init; } = true; + /// + /// Gets or inits the value of the exclude private + /// + public IEnumerable AccessModifiers { get; init; } = new List + { + "public", + "internal", + "private", + "protected", + "protected private", + "protected internal", + }; + /// /// Gets the syntax kind /// diff --git a/src/DotnetDocument/Extensions/MemberDeclarationSyntaxExtensions.cs b/src/DotnetDocument/Extensions/MemberDeclarationSyntaxExtensions.cs new file mode 100644 index 0000000..5dae0c4 --- /dev/null +++ b/src/DotnetDocument/Extensions/MemberDeclarationSyntaxExtensions.cs @@ -0,0 +1,57 @@ +using System; +using System.Linq; +using DotnetDocument.Configuration; +using DotnetDocument.Syntax; +using Microsoft.CodeAnalysis.CSharp.Syntax; + +namespace DotnetDocument.Extensions +{ + public static class MemberDeclarationSyntaxExtensions + { + public static bool ShouldDocument(this MemberDeclarationSyntax node, MemberDocumentationOptionsBase options) + { + var shouldDocument = false; + + foreach (var modifier in options.AccessModifiers) + { + var modifierArray = modifier.Split(" "); + + if (node != null) + { + if (modifierArray.Length > 1) + { + if (node.Modifiers.Any(m => m.Text.Equals(modifierArray[0], StringComparison.Ordinal)) && + node.Modifiers.Any(m => m.Text.Equals(modifierArray[1], StringComparison.Ordinal)) && + !SyntaxUtils.IsDocumented(node)) + { + shouldDocument = true; + + break; + } + + } + else + { + if (node.Modifiers.All(m => m.Text.Equals(modifier, StringComparison.Ordinal)) && + !SyntaxUtils.IsDocumented(node)) + { + shouldDocument = true; + + break; + } + + if (node.Modifiers.Any() && node.Modifiers[0].Text.Equals(modifier, StringComparison.Ordinal) && + !SyntaxUtils.IsDocumented(node)) + { + shouldDocument = true; + + break; + } + } + } + } + + return shouldDocument; + } + } +} diff --git a/src/DotnetDocument/Strategies/Abstractions/DocumentationStrategyBase.cs b/src/DotnetDocument/Strategies/Abstractions/DocumentationStrategyBase.cs index be37679..02aac7c 100644 --- a/src/DotnetDocument/Strategies/Abstractions/DocumentationStrategyBase.cs +++ b/src/DotnetDocument/Strategies/Abstractions/DocumentationStrategyBase.cs @@ -3,6 +3,7 @@ using DotnetDocument.Syntax; using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.CSharp.Syntax; namespace DotnetDocument.Strategies.Abstractions { @@ -18,6 +19,11 @@ public abstract class DocumentationStrategyBase : IDocumentationStrategy wher /// An enumerable of syntax kind public abstract IEnumerable GetSupportedKinds(); + public bool ShouldDocument(SyntaxNode node) => + ShouldDocument(node as T ?? throw new InvalidOperationException()); + + public abstract bool ShouldDocument(T node); + /// /// Applies the node /// diff --git a/src/DotnetDocument/Strategies/Abstractions/IDocumentationStrategy.cs b/src/DotnetDocument/Strategies/Abstractions/IDocumentationStrategy.cs index 64ca384..d0ed84e 100644 --- a/src/DotnetDocument/Strategies/Abstractions/IDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/Abstractions/IDocumentationStrategy.cs @@ -9,6 +9,7 @@ namespace DotnetDocument.Strategies.Abstractions /// public interface IDocumentationStrategy { + bool ShouldDocument(SyntaxNode node); /// /// Gets the supported kinds /// diff --git a/src/DotnetDocument/Strategies/ClassDocumentationStrategy.cs b/src/DotnetDocument/Strategies/ClassDocumentationStrategy.cs index 2a37d1a..b7463ed 100644 --- a/src/DotnetDocument/Strategies/ClassDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/ClassDocumentationStrategy.cs @@ -1,6 +1,7 @@ using System.Collections.Generic; using System.Linq; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using DotnetDocument.Syntax; @@ -32,6 +33,7 @@ public class ClassDocumentationStrategy : DocumentationStrategyBase private readonly ClassDocumentationOptions _options; + public override bool ShouldDocument(ClassDeclarationSyntax node) => node.ShouldDocument(_options); /// /// Initializes a new instance of the class /// diff --git a/src/DotnetDocument/Strategies/ConstructorDocumentationStrategy.cs b/src/DotnetDocument/Strategies/ConstructorDocumentationStrategy.cs index 0c763e6..45499af 100644 --- a/src/DotnetDocument/Strategies/ConstructorDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/ConstructorDocumentationStrategy.cs @@ -1,6 +1,7 @@ using System.Collections.Generic; using System.Linq; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using DotnetDocument.Syntax; @@ -32,6 +33,7 @@ public class ConstructorDocumentationStrategy : DocumentationStrategyBase private readonly CtorDocumentationOptions _options; + public override bool ShouldDocument(ConstructorDeclarationSyntax node) => node.ShouldDocument(_options); /// /// Initializes a new instance of the class /// diff --git a/src/DotnetDocument/Strategies/DefaultDocumentationStrategy.cs b/src/DotnetDocument/Strategies/DefaultDocumentationStrategy.cs index 0099176..f0ccefa 100644 --- a/src/DotnetDocument/Strategies/DefaultDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/DefaultDocumentationStrategy.cs @@ -1,5 +1,7 @@ using System.Collections.Generic; +using System.Linq; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using DotnetDocument.Syntax; @@ -36,6 +38,7 @@ public class DefaultDocumentationStrategy : DocumentationStrategyBase private readonly DefaultMemberDocumentationOptions _options; + public override bool ShouldDocument(MemberDeclarationSyntax node) => node.ShouldDocument(_options); /// /// Initializes a new instance of the class /// diff --git a/src/DotnetDocument/Strategies/EnumDocumentationStrategy.cs b/src/DotnetDocument/Strategies/EnumDocumentationStrategy.cs index 08cd3f3..905cb22 100644 --- a/src/DotnetDocument/Strategies/EnumDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/EnumDocumentationStrategy.cs @@ -1,5 +1,6 @@ using System.Collections.Generic; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using Microsoft.CodeAnalysis.CSharp; @@ -30,6 +31,7 @@ public class EnumDocumentationStrategy : DocumentationStrategyBase private readonly EnumDocumentationOptions _options; + public override bool ShouldDocument(EnumDeclarationSyntax node) => node.ShouldDocument(_options); /// /// Initializes a new instance of the class /// diff --git a/src/DotnetDocument/Strategies/EnumMemberDocumentationStrategy.cs b/src/DotnetDocument/Strategies/EnumMemberDocumentationStrategy.cs index 1b41999..563b830 100644 --- a/src/DotnetDocument/Strategies/EnumMemberDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/EnumMemberDocumentationStrategy.cs @@ -1,5 +1,6 @@ using System.Collections.Generic; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using Microsoft.CodeAnalysis.CSharp; @@ -30,6 +31,13 @@ public class EnumMemberDocumentationStrategy : DocumentationStrategyBase private readonly EnumMemberDocumentationOptions _options; + /// + /// + /// + /// + /// + public override bool ShouldDocument(EnumMemberDeclarationSyntax node) => node.ShouldDocument(_options); + /// /// Initializes a new instance of the class /// diff --git a/src/DotnetDocument/Strategies/InterfaceDocumentationStrategy.cs b/src/DotnetDocument/Strategies/InterfaceDocumentationStrategy.cs index 85bf8b2..95cc3f6 100644 --- a/src/DotnetDocument/Strategies/InterfaceDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/InterfaceDocumentationStrategy.cs @@ -1,6 +1,7 @@ using System.Collections.Generic; using System.Linq; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using DotnetDocument.Syntax; @@ -32,6 +33,7 @@ public class InterfaceDocumentationStrategy : DocumentationStrategyBase private readonly InterfaceDocumentationOptions _options; + public override bool ShouldDocument(InterfaceDeclarationSyntax node) => node.ShouldDocument(_options); /// /// Initializes a new instance of the class /// @@ -51,6 +53,7 @@ public override IEnumerable GetSupportedKinds() => new[] SyntaxKind.InterfaceDeclaration }; + /// /// Applies the node /// diff --git a/src/DotnetDocument/Strategies/MethodDocumentationStrategy.cs b/src/DotnetDocument/Strategies/MethodDocumentationStrategy.cs index d57b7b7..7b3279a 100644 --- a/src/DotnetDocument/Strategies/MethodDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/MethodDocumentationStrategy.cs @@ -1,6 +1,7 @@ using System.Collections.Generic; using System.Linq; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using DotnetDocument.Syntax; @@ -52,6 +53,8 @@ public override IEnumerable GetSupportedKinds() => new[] SyntaxKind.MethodDeclaration }; + public override bool ShouldDocument(MethodDeclarationSyntax node) => node.ShouldDocument(_options); + /// /// Applies the node /// diff --git a/src/DotnetDocument/Strategies/PropertyDocumentationStrategy.cs b/src/DotnetDocument/Strategies/PropertyDocumentationStrategy.cs index ff5c6b6..03d6929 100644 --- a/src/DotnetDocument/Strategies/PropertyDocumentationStrategy.cs +++ b/src/DotnetDocument/Strategies/PropertyDocumentationStrategy.cs @@ -1,6 +1,7 @@ using System.Collections.Generic; using System.Linq; using DotnetDocument.Configuration; +using DotnetDocument.Extensions; using DotnetDocument.Format; using DotnetDocument.Strategies.Abstractions; using Humanizer; @@ -32,6 +33,13 @@ public class PropertyDocumentationStrategy : DocumentationStrategyBase private readonly PropertyDocumentationOptions _options; + /// + /// + /// + /// + /// + public override bool ShouldDocument(PropertyDeclarationSyntax node) => node.ShouldDocument(_options); + /// /// Initializes a new instance of the class /// diff --git a/src/DotnetDocument/Syntax/DocumentationSyntaxWalker.cs b/src/DotnetDocument/Syntax/DocumentationSyntaxWalker.cs index 85aa0c3..3b1564a 100644 --- a/src/DotnetDocument/Syntax/DocumentationSyntaxWalker.cs +++ b/src/DotnetDocument/Syntax/DocumentationSyntaxWalker.cs @@ -26,6 +26,11 @@ public class DocumentationSyntaxWalker : CSharpSyntaxWalker /// Gets the value of the nodes with xml doc /// public IList NodesWithXmlDoc { get; } = new List(); + + /// + /// Gets the value of all nodes + /// + public IList AllNodes { get; } = new List(); /// /// Gets the value of the nodes without xml doc