Merge pull request #34 from candy-kingdom/feature/32-optional-private…

…-members

Add support for including non-public members in the output

README.md

@@ -27,6 +27,7 @@ const string output = "./docs";
 await new SummaryPipeline()
     .UseRoslynParser(input)
     .UseMdRenderer(output)
+    .UseDefaultFilters()
     .Run();
 ```
 

docs/FilterMemberPipe.md

@@ -0,0 +1,13 @@
+# Summary.Pipes.Filters.FilterMemberPipe
+```cs
+public class FilterMemberPipe : IPipe<Doc, Doc>
+```
+
+A simple pipe that filters all members inside the document using the specified predicate.
+
+## Methods
+### Run(Doc)
+```cs
+public Task<Doc> Run(Doc input)
+```
+

docs/SummaryPipeline.md

@@ -19,6 +19,15 @@ public ILoggerFactory LoggerFactory { get; }
 
 The factory that provides logger implementations.
 
+### Filters
+```cs
+public List<IPipe<Doc, Doc>> Filters { get; }
+```
+
+The list of all filters applied after the document is parsed.
+
+_Filters are applied in a separate run after the document is successfully parsed._
+
 ## Methods
 ### UseLoggerFactory(ILoggerFactory)
 ```cs
@@ -27,6 +36,13 @@ public Options UseLoggerFactory(ILoggerFactory loggers)
 
 Specifies the logger factory that will be used to create loggers for the pipeline.
 
+### Customize(Func<Options, Options>)
+```cs
+public SummaryPipeline Customize(Func<Options, Options> options)
+```
+
+Customizes the default pipeline options using the specified delegate.
+
 ### ParseWith(Func<Options, IPipe<Unit, Doc>>)
 ```cs
 public SummaryPipeline ParseWith(Func<Options, IPipe<Unit, Doc>> parser)

docs/SummaryPipelineExtensions.md

@@ -0,0 +1,64 @@
+# Summary.Pipelines.SummaryPipelineExtensions
+```cs
+public static class SummaryPipelineExtensions
+```
+
+Convenient extensions for [`SummaryPipeline`](./SummaryPipeline.md).
+
+## Methods
+### UseLoggerFactory(SummaryPipeline, ILoggerFactory)
+```cs
+public static SummaryPipeline UseLoggerFactory(this SummaryPipeline self, ILoggerFactory factory)
+```
+
+Specifies the logger factory to use for pipes inside the pipeline.
+
+_This method should be called _before_ anything else so that_
+_given logger factory is passed into all subsequent calls._
+
+### UseDefaultFilters(SummaryPipeline)
+```cs
+public static SummaryPipeline UseDefaultFilters(this SummaryPipeline self)
+```
+
+Enables default filters for the given pipeline (i.e. a filter that removes all non-public members).
+
+### IncludeAtLeast(SummaryPipeline, AccessModifier)
+```cs
+public static SummaryPipeline IncludeAtLeast(this SummaryPipeline self, AccessModifier access)
+```
+
+Includes only members that have at least the given access modifier.
+
+#### Example
+In order to include both `internal` and `public` members in the generated docs,
+you can call this method as follows:
+```cs
+var pipeline = ...;
+
+pipeline.IncludeAtLeast(AccessModifier.Internal);
+```
+
+### IncludeOnly(SummaryPipeline, AccessModifier)
+```cs
+public static SummaryPipeline IncludeOnly(this SummaryPipeline self, AccessModifier access)
+```
+
+Includes only members that have at least the given access modifier.
+
+#### Example
+In order to include onl `internal` members in the generated docs,
+you can call this method as follows:
+```cs
+var pipeline = ...;
+
+pipeline.IncludeOnly(AccessModifier.Internal);
+```
+
+### UseFilter(SummaryPipeline, IPipe<Doc, Doc>)
+```cs
+public static SummaryPipeline UseFilter(this SummaryPipeline self, IPipe<Doc, Doc> filter)
+```
+
+Adds the given filter into the pipeline.
+

src/Cli/Program.cs

@@ -6,9 +6,9 @@
 const string input = "../../../../../src/";
 const string output = "../../../../../docs";
 
-var options = new SummaryPipeline.Options().UseLoggerFactory(new ConsoleLoggerFactory());
-
-await new SummaryPipeline(options)
+await new SummaryPipeline()
+    .UseLoggerFactory(new ConsoleLoggerFactory())
     .UseRoslynParser(input)
     .UseMdRenderer(output)
+    .UseDefaultFilters()
     .Run();

src/Core/AccessModifier.cs

@@ -3,25 +3,28 @@
 /// <summary>
 ///     An access modifier of a <see cref="DocMember"/> (e.g. `private`, `public`, etc.).
 /// </summary>
+/// <remarks>
+///     The modifiers are ordered starting from the smallest one (<see cref="Private"/>).
+/// </remarks>
 public enum AccessModifier
 {
     /// <summary>
-    ///     The `public` keyword access modifier.
+    ///     The `private` keyword access modifier.
     /// </summary>
-    Public,
+    Private,
 
     /// <summary>
     ///     The `protected` keyword access modifier.
     /// </summary>
     Protected,
 
     /// <summary>
-    ///     The `private` keyword access modifier.
+    ///     The `internal` keyword access modifier.
     /// </summary>
-    Private,
+    Internal,
 
     /// <summary>
-    ///     The `internal` keyword access modifier.
+    ///     The `public` keyword access modifier.
     /// </summary>
-    Internal,
+    Public,
 }

src/Core/Pipelines/SummaryPipeline.cs

@@ -1,6 +1,7 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Summary.Pipes;
+using Summary.Pipes.Filters;
 
 namespace Summary.Pipelines;
 
@@ -37,12 +38,13 @@ public Options UseLoggerFactory(ILoggerFactory loggers) =>
         private Options With<T>(T _) => this;
     }
 
-    private readonly Options _options;
-    private readonly ILogger<SummaryPipeline> _logger;
+    private ILogger<SummaryPipeline> _logger = null!;
+    private Options _options = null!;
 
     private IPipe<Unit, Doc> _parser = new FuncPipe<Unit, Doc>(_ => Doc.Empty);
     private IPipe<Doc, Unit> _render = new FuncPipe<Doc, Unit>(_ => Unit.Value);
 
+
     /// <summary>
     ///     Constructs the documentation generation pipeline with default options.
     /// </summary>
@@ -51,11 +53,22 @@ public SummaryPipeline() : this(new()) { }
     /// <summary>
     ///     Constructs the documentation generation pipeline with the specified options.
     /// </summary>
-    public SummaryPipeline(Options options)
-    {
-        _options = options;
-        _logger = options.LoggerFactory.CreateLogger<SummaryPipeline>();
-    }
+    public SummaryPipeline(Options options) =>
+        Set(options);
+
+    /// <summary>
+    ///     The list of all filters applied after the document is parsed.
+    /// </summary>
+    /// <remarks>
+    ///     Filters are applied in a separate run after the document is successfully parsed.
+    /// </remarks>
+    public List<IPipe<Doc, Doc>> Filters { get; } = new();
+
+    /// <summary>
+    ///     Customizes the default pipeline options using the specified delegate.
+    /// </summary>
+    public SummaryPipeline Customize(Func<Options, Options> options) =>
+        Set(options(_options));
 
     /// <summary>
     ///     Specifies the custom parser with logging support for this pipeline.
@@ -100,6 +113,8 @@ public async Task Run()
     {
         var doc = await Parse();
 
+        doc = await Filter(doc);
+
         await Render(doc);
 
         Task<Doc> Parse()
@@ -109,11 +124,29 @@ Task<Doc> Parse()
             return _parser.Run();
         }
 
+        async Task<Doc> Filter(Doc doc)
+        {
+            using var _ = _logger.BeginScope(nameof(Filter));
+
+            foreach (var filter in Filters)
+                doc = await filter.Run(doc);
+
+            return doc;
+        }
+
         Task Render(Doc doc)
         {
             using var _ = _logger.BeginScope(nameof(Render));
 
             return _render.Run(doc);
         }
     }
+
+    private SummaryPipeline Set(Options options)
+    {
+        _options = options;
+        _logger = options.LoggerFactory.CreateLogger<SummaryPipeline>();
+
+        return this;
+    }
 }

src/Core/Pipelines/SummaryPipelineExtensions.cs

@@ -0,0 +1,67 @@
+using Microsoft.Extensions.Logging;
+using Summary.Pipes;
+using Summary.Pipes.Filters;
+
+namespace Summary.Pipelines;
+
+/// <summary>
+///     Convenient extensions for <see cref="SummaryPipeline"/>.
+/// </summary>
+public static class SummaryPipelineExtensions
+{
+    /// <summary>
+    ///     Specifies the logger factory to use for pipes inside the pipeline.
+    /// </summary>
+    /// <remarks>
+    ///     This method should be called <i>before</i> anything else so that
+    ///     given logger factory is passed into all subsequent calls.
+    /// </remarks>
+    public static SummaryPipeline UseLoggerFactory(this SummaryPipeline self, ILoggerFactory factory) =>
+        self.Customize(options => options.UseLoggerFactory(factory));
+
+    /// <summary>
+    ///     Enables default filters for the given pipeline (i.e. a filter that removes all non-public members).
+    /// </summary>
+    public static SummaryPipeline UseDefaultFilters(this SummaryPipeline self) => self
+        .IncludeOnly(AccessModifier.Public);
+
+    /// <summary>
+    ///     Includes only members that have at least the given access modifier.
+    /// </summary>
+    /// <example>
+    ///     In order to include both <c>internal</c> and <c>public</c> members in the generated docs,
+    ///     you can call this method as follows:
+    ///     <para><code>
+    ///         var pipeline = ...;
+    ///
+    ///         pipeline.IncludeAtLeast(AccessModifier.Internal);
+    ///     </code></para>
+    /// </example>
+    public static SummaryPipeline IncludeAtLeast(this SummaryPipeline self, AccessModifier access) => self
+        .UseFilter(new FilterMemberPipe(x => x.Access >= access));
+
+    /// <summary>
+    ///     Includes only members that have at least the given access modifier.
+    /// </summary>
+    /// <example>
+    ///     In order to include onl <c>internal</c> members in the generated docs,
+    ///     you can call this method as follows:
+    ///     <para><code>
+    ///         var pipeline = ...;
+    ///
+    ///         pipeline.IncludeOnly(AccessModifier.Internal);
+    ///     </code></para>
+    /// </example>
+    public static SummaryPipeline IncludeOnly(this SummaryPipeline self, AccessModifier access) => self
+        .UseFilter(new FilterMemberPipe(x => x.Access == access));
+
+    /// <summary>
+    ///     Adds the given filter into the pipeline.
+    /// </summary>
+    /// <seealso cref="SummaryPipeline.Filters"/>
+    public static SummaryPipeline UseFilter(this SummaryPipeline self, IPipe<Doc, Doc> filter)
+    {
+        self.Filters.Add(filter);
+        return self;
+    }
+}

src/Core/Pipes/Filters/FilterMemberPipe.cs

@@ -0,0 +1,28 @@
+namespace Summary.Pipes.Filters;
+
+/// <summary>
+///     A simple pipe that filters all members inside the document using the specified predicate.
+/// </summary>
+public class FilterMemberPipe : IPipe<Doc, Doc>
+{
+    private readonly Predicate<DocMember> _p  ;
+
+    public FilterMemberPipe(Predicate<DocMember> p) =>
+        _p = p;
+
+    public Task<Doc> Run(Doc input) =>
+        Task.FromResult(new Doc(Filtered(input.Members)));
+
+    private DocMember[] Filtered(DocMember[] members) =>
+        members
+            .Where(x => _p(x))
+            .Select(Filtered)
+            .ToArray();
+
+    private DocMember Filtered(DocMember member) => member switch
+    {
+        DocTypeDeclaration type => type with { Members = Filtered(type.Members) },
+
+        _ => member,
+    };
+}