Merge 01a8a1d into 64ba963

Author: yufeih

docs/docs/dotnet-api-docs.md

@@ -154,45 +154,18 @@ To disable the default filtering rules, set the `disableDefaultFilter` property
 
 To show private methods, set the `includePrivateMembers` config to `true`. When enabled, internal only langauge keywords such as `private` or `internal` starts to appear in the declaration of all APIs, to accurately reflect API accessibility.
 
-There are two ways of customizing the API filters:
+### The `<exclude />` documentation comment
 
-### Custom with Code
+The `<exclude />` documentation comment excludes the type or member on a per API basis using C# documentation comment:
 
-To use a custom filtering with code:
-
-1. Use docfx .NET API generation as a NuGet library:
-
-```xml
-<PackageReference Include="Docfx.Dotnet" Version="2.62.0" />
-```
-
-2. Configure the filter options:
-
-```cs
-var options = new DotnetApiOptions
-{
-    // Filter based on types
-    IncludeApi = symbol => ...
-
-    // Filter based on attributes
-    IncludeAttribute = symbol => ...
-}
-
-await DotnetApiCatalog.GenerateManagedReferenceYamlFiles("docfx.json", options);
+```csharp
+/// <exclude />
+public class Foo { }
 ```
 
-The filter callbacks takes an [`ISymbol`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.isymbol?view=roslyn-dotnet) interface and produces an [`SymbolIncludeState`](../api/Docfx.Dotnet.SymbolIncludeState.yml) enum to choose between include the API, exclude the API or use the default filtering behavior.
-
-The callbacks are raised before applying the default rules but after processing type accessibility rules. Private types and members cannot be marked as include unless `includePrivateMembers` is true.
-
-Hiding the parent symbol also hides all of its child symbols, e.g.:
-- If a namespace is hidden, all child namespaces and types underneath it are hidden.
-- If a class is hidden, all nested types underneath it are hidden.
-- If an interface is hidden, explicit implementations of that interface are also hidden.
-
-### Custom with Filter Rules
+### Custom filter rules
 
-To add additional filter rules, add a custom YAML file and set the `filter` property in `docfx.json` to point to the custom YAML filter:
+To bulk filter APIs with custom filter rules, add a custom YAML file and set the `filter` property in `docfx.json` to point to the custom YAML filter:
 
 ```json
 {
@@ -265,3 +238,38 @@ apiRules:
 ```
 
 Where the `ctorArguments` property specifies a list of match conditions based on constructor parameters and the `ctorNamedArguments` property specifies match conditions using named constructor arguments.
+
+
+### Custom code filter
+
+To use a custom filtering with code:
+
+1. Use docfx .NET API generation as a NuGet library:
+
+```xml
+<PackageReference Include="Docfx.Dotnet" Version="2.62.0" />
+```
+
+2. Configure the filter options:
+
+```cs
+var options = new DotnetApiOptions
+{
+    // Filter based on types
+    IncludeApi = symbol => ...
+
+    // Filter based on attributes
+    IncludeAttribute = symbol => ...
+}
+
+await DotnetApiCatalog.GenerateManagedReferenceYamlFiles("docfx.json", options);
+```
+
+The filter callbacks takes an [`ISymbol`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.isymbol?view=roslyn-dotnet) interface and produces an [`SymbolIncludeState`](../api/Docfx.Dotnet.SymbolIncludeState.yml) enum to choose between include the API, exclude the API or use the default filtering behavior.
+
+The callbacks are raised before applying the default rules but after processing type accessibility rules. Private types and members cannot be marked as include unless `includePrivateMembers` is true.
+
+Hiding the parent symbol also hides all of its child symbols, e.g.:
+- If a namespace is hidden, all child namespaces and types underneath it are hidden.
+- If a class is hidden, all nested types underneath it are hidden.
+- If an interface is hidden, explicit implementations of that interface are also hidden.

src/Docfx.Dotnet/SymbolFilter.cs

@@ -26,24 +26,25 @@ public SymbolFilter(ExtractMetadataConfig config, DotnetApiOptions options)
 
     public bool IncludeApi(ISymbol symbol)
     {
-        return !IsCompilerGeneratedDisplayClass(symbol) && IsSymbolAccessible(symbol) && IncludeApiCore(symbol);
-
-        bool IncludeApiCore(ISymbol symbol)
+        return _cache.GetOrAdd(symbol, _ =>
         {
-            return _cache.GetOrAdd(symbol, _ => _options.IncludeApi?.Invoke(_) switch
-            {
-                SymbolIncludeState.Include => true,
-                SymbolIncludeState.Exclude => false,
-                _ => IncludeApiDefault(symbol),
-            });
-        }
+            return !IsCompilerGeneratedDisplayClass(symbol) &&
+                IsSymbolAccessible(symbol) &&
+                !HasExcludeDocumentComment(symbol) &&
+                _options.IncludeApi?.Invoke(_) switch
+                {
+                    SymbolIncludeState.Include => true,
+                    SymbolIncludeState.Exclude => false,
+                    _ => IncludeApiDefault(symbol),
+                };
+        });
 
         bool IncludeApiDefault(ISymbol symbol)
         {
             if (_filterRule is not null && !_filterRule.CanVisitApi(RoslynFilterData.GetSymbolFilterData(symbol)))
                 return false;
 
-            return symbol.ContainingSymbol is null || IncludeApiCore(symbol.ContainingSymbol);
+            return symbol.ContainingSymbol is null || IncludeApi(symbol.ContainingSymbol);
         }
 
         static bool IsCompilerGeneratedDisplayClass(ISymbol symbol)
@@ -54,24 +55,22 @@ static bool IsCompilerGeneratedDisplayClass(ISymbol symbol)
 
     public bool IncludeAttribute(ISymbol symbol)
     {
-        return IsSymbolAccessible(symbol) && IncludeAttributeCore(symbol);
-
-        bool IncludeAttributeCore(ISymbol symbol)
+        return _attributeCache.GetOrAdd(symbol, _ =>
         {
-            return _attributeCache.GetOrAdd(symbol, _ => _options.IncludeAttribute?.Invoke(_) switch
+            return IsSymbolAccessible(symbol) && !HasExcludeDocumentComment(symbol) && _options.IncludeAttribute?.Invoke(_) switch
             {
                 SymbolIncludeState.Include => true,
                 SymbolIncludeState.Exclude => false,
                 _ => IncludeAttributeDefault(symbol),
-            });
-        }
+            };
+        });
 
         bool IncludeAttributeDefault(ISymbol symbol)
         {
             if (_filterRule is not null && !_filterRule.CanVisitAttribute(RoslynFilterData.GetSymbolFilterData(symbol)))
                 return false;
 
-            return symbol.ContainingSymbol is null || IncludeAttributeCore(symbol.ContainingSymbol);
+            return symbol.ContainingSymbol is null || IncludeAttribute(symbol.ContainingSymbol);
         }
     }
 
@@ -127,4 +126,12 @@ bool IsEiiAndIncludesContainingSymbols(IEnumerable<ISymbol> symbols)
             return symbols.Any() && symbols.All(s => IncludeApi(s.ContainingSymbol));
         }
     }
+
+    private static bool HasExcludeDocumentComment(ISymbol symbol)
+    {
+        return symbol.GetDocumentationCommentXml() is { } xml && (
+            xml.Contains("<exclude/>") ||
+            xml.Contains("<exclude>") ||
+            xml.Contains("<exclude "));
+    }
 }

test/Docfx.Dotnet.Tests/GenerateMetadataFromCSUnitTest.cs

@@ -3709,4 +3709,25 @@ public interface IFoo { void Bar(); }
         Assert.Equal("public class Foo : IFoo", foo.Syntax.Content[SyntaxLanguage.CSharp]);
         Assert.Equal("void IFoo.Bar()", foo.Items[0].Syntax.Content[SyntaxLanguage.CSharp]);
     }
+
+    [Fact]
+    public void TestExcludeDocumentationComment()
+    {
+        var code =
+            """
+            namespace Test
+            {
+                public class Foo
+                {
+                    /// <exclude />
+                    public void F1() {}
+                }
+            }
+            """;
+
+        var output = Verify(code);
+        var foo = output.Items[0].Items[0];
+        Assert.Equal("public class Foo", foo.Syntax.Content[SyntaxLanguage.CSharp]);
+        Assert.Empty(foo.Items);
+    }
 }

test/docfx.Snapshot.Tests/SamplesTest.Seed.Windows/pdf/toc.pdf.verified.json

@@ -712,60 +712,52 @@
             "PageNumber": 16,
             "Coordinates": {
               "Left": 28,
-              "Top": 211.24994
+              "Top": 552.50006
             }
           }
         }
       ]
     },
     {
       "Number": 15,
-      "NumberOfImages": 1,
-      "Text": "15ImageMermaid DiagramsFlowchartCode SnippetThe example highlights lines 2, line 5 to 7 and lines 9 to the end of the file.MY TODOThis is a TODO.TextOneTwoHardRoundDecisionResult 1Result 2",
-      "Links": [
-        {
-          "Uri": "https://learn.microsoft.com/en-us/media/learn/not-found/learn-not-found-light-mode.png?branch=main"
-        },
-        {
-          "Uri": "https://learn.microsoft.com/en-us/media/learn/not-found/learn-not-found-light-mode.png?branch=main"
-        }
-      ]
-    },
-    {
-      "Number": 16,
-      "Text": "16Math ExpressionsThis sentence uses $ delimiters to show math inline: The Cauchy-Schwarz InequalityThis expression uses \\$ to display a dollar sign: To split $100 in half, we calculate using System;using Azure;using Azure.Storage;using Azure.Storage.Blobs;class Program{    static void Main(string[] args)    {        // Define the connection string for the storage account        string connectionString = \"DefaultEndpointsProtocol=https;AccountName=<your-account-name>;AccountKey=<your-account-key>;EndpointSuffix=core.windows.net\";        // Create a new BlobServiceClient using the connection string        var blobServiceClient = new BlobServiceClient(connectionString);        // Create a new container        var container = blobServiceClient.CreateBlobContainer(\"mycontainer\");        // Upload a file to the container        using (var fileStream = File.OpenRead(\"path/to/file.txt\"))        {            container.UploadBlob(\"file.txt\", fileStream);        }        // Download the file from the container        var downloadedBlob = container.GetBlobClient(\"file.txt\").Download();        using (var fileStream = File.OpenWrite(\"path/to/downloaded-file.txt\"))        {            downloadedBlob.Value.Content.CopyTo(fileStream);        }    }}",
+      "Text": "15ImageMermaid DiagramsFlowchartCode SnippetThe example highlights lines 2, line 5 to 7 and lines 9 to the end of the file.MY TODOThis is a TODO.TextOneTwoHardRoundDecisionResult 1Result 2using System;using Azure;using Azure.Storage;using Azure.Storage.Blobs;class Program{    static void Main(string[] args)    {        // Define the connection string for the storage account        string connectionString = \"DefaultEndpointsProtocol=https;AccountName=<your-account-name>;AccountKey=<your-account-key>;EndpointSuffix=core.windows.net\";        // Create a new BlobServiceClient using the connection string        var blobServiceClient = new BlobServiceClient(connectionString);        // Create a new container        var container = blobServiceClient.CreateBlobContainer(\"mycontainer\");        // Upload a file to the container        using (var fileStream = File.OpenRead(\"path/to/file.txt\"))",
       "Links": []
     },
     {
-      "Number": 17,
-      "Text": "17Custom Syntax HighlightingTabsLinuxWindowsThe above tab group was created with the following syntax:Tabs are indicated by using a specific link syntax within a Markdown header. The syntax can be describedas follows:A tab starts with a Markdown header, #, and is followed by a Markdown link [](). The text of the link willbecome the text of the tab header, displayed to the customer. In order for the header to be recognizedas a tab, the link itself must start with #tab/ and be followed by an ID representing the content of thetab. The ID is used to sync all same-ID tabs across the page. Using the above example, when a userselects a tab with the link #tab/windows, all tabs with the link #tab/windows on the page will be selected.Dependent tabsIt's possible to make the selection in one set of tabs dependent on the selection in another set of tabs.Here's an example of that in action:resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {  name: 'hello'  // (...)}Content for Linux...# [Linux](#tab/linux)Content for Linux...# [Windows](#tab/windows)Content for Windows...---# [Tab Display Name](#tab/tab-id)",
+      "Number": 16,
+      "Text": "16Math ExpressionsThis sentence uses $ delimiters to show math inline: The Cauchy-Schwarz InequalityThis expression uses \\$ to display a dollar sign: To split $100 in half, we calculate Custom Syntax HighlightingTabsLinuxWindowsThe above tab group was created with the following syntax:        {            container.UploadBlob(\"file.txt\", fileStream);        }        // Download the file from the container        var downloadedBlob = container.GetBlobClient(\"file.txt\").Download();        using (var fileStream = File.OpenWrite(\"path/to/downloaded-file.txt\"))        {            downloadedBlob.Value.Content.CopyTo(fileStream);        }    }}resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {  name: 'hello'  // (...)}Content for Linux...# [Linux](#tab/linux)",
       "Links": [
         {
           "Goto": {
-            "PageNumber": 17,
+            "PageNumber": 16,
             "Coordinates": {
               "Left": 28,
-              "Top": 574.99994
+              "Top": 181.24994
             }
           }
         }
       ]
     },
     {
-      "Number": 18,
-      "Text": "18.NETTypeScriptREST APINotice how changing the Linux/Windows selection above changes the content in the .NET andTypeScript tabs. This is because the tab group defines two versions for each .NET and TypeScript, wherethe Windows/Linux selection above determines which version is shown for .NET/TypeScript. Here's themarkup that shows how this is done:.NET content for Linux...# [.NET](#tab/dotnet/linux).NET content for Linux...# [.NET](#tab/dotnet/windows).NET content for Windows...# [TypeScript](#tab/typescript/linux)TypeScript content for Linux...# [TypeScript](#tab/typescript/windows)TypeScript content for Windows...# [REST API](#tab/rest)REST API content, independent of platform...---",
+      "Number": 17,
+      "Text": "17Tabs are indicated by using a specific link syntax within a Markdown header. The syntax can be describedas follows:A tab starts with a Markdown header, #, and is followed by a Markdown link [](). The text of the link willbecome the text of the tab header, displayed to the customer. In order for the header to be recognizedas a tab, the link itself must start with #tab/ and be followed by an ID representing the content of thetab. The ID is used to sync all same-ID tabs across the page. Using the above example, when a userselects a tab with the link #tab/windows, all tabs with the link #tab/windows on the page will be selected.Dependent tabsIt's possible to make the selection in one set of tabs dependent on the selection in another set of tabs.Here's an example of that in action:.NETTypeScriptREST APINotice how changing the Linux/Windows selection above changes the content in the .NET andTypeScript tabs. This is because the tab group defines two versions for each .NET and TypeScript, wherethe Windows/Linux selection above determines which version is shown for .NET/TypeScript. Here's themarkup that shows how this is done:Content for Linux...# [Windows](#tab/windows)Content for Windows...---# [Tab Display Name](#tab/tab-id).NET content for Linux...# [.NET](#tab/dotnet/linux).NET content for Linux...# [.NET](#tab/dotnet/windows).NET content for Windows...",
       "Links": [
         {
           "Goto": {
-            "PageNumber": 18,
+            "PageNumber": 17,
             "Coordinates": {
               "Left": 28,
-              "Top": 732.49994
+              "Top": 324.49994
             }
           }
         }
       ]
     },
+    {
+      "Number": 18,
+      "Text": "18# [TypeScript](#tab/typescript/linux)TypeScript content for Linux...# [TypeScript](#tab/typescript/windows)TypeScript content for Windows...# [REST API](#tab/rest)REST API content, independent of platform...---",
+      "Links": []
+    },
     {
       "Number": 19,
       "Text": "19ClassesClass1This is a test class.StructsIssue5432Namespace BuildFromAssembly",