From 5b6693ba79401d97074f202d38e69adfa2e70492 Mon Sep 17 00:00:00 2001 From: Clinton Ingram Date: Sat, 25 Nov 2023 22:55:08 -0800 Subject: [PATCH] v1.4.0 --- readme.md | 15 ++++++++++++--- src/Directory.Build.props | 4 ---- src/InheritDoc/CecilExtensions.cs | 2 +- src/InheritDoc/readme.md | 13 +++++++++++-- 4 files changed, 24 insertions(+), 10 deletions(-) diff --git a/readme.md b/readme.md index 3bed2a4..e619c6c 100644 --- a/readme.md +++ b/readme.md @@ -3,14 +3,14 @@ InheritDoc ========== -This [MSBuild Task]( https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-tasks) automatically replaces `` tags in your .NET XML documentation with the actual inherited docs. By integrating with MSBuild, this tool has access to the exact arguments passed to the compiler -- including all assembly references -- making it both simpler and more capable than other documentation post-processing tools. As it processes `` elements, it is able to accurately resolve base types whether they come from the target framework, referenced NuGet packages, or project references. This allows intelligent mapping of documentation from base types and members to yours. For example, it can identify when you change the name of a method parameter from the base type’s definition and update the documentation accordingly. It can also remove documentation for non-public types/members to reduce the size of your published XML docs. +This [MSBuild Task]( https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-tasks) automatically replaces `` tags in your .NET XML documentation with the actual inherited docs. How to Use It ------------- 1) Add some `` tags to your XML documentation comments. - This tool’s handling of `` tags is based on the draft [design document]( https://github.com/dotnet/csharplang/blob/812e220fe2b964d17f353cb684aa341418618b6e/proposals/inheritdoc.md) used for Roslyn's support in Visual Studio, which is in turn based on the `` support in [Sandcastle Help File Builder]( https://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm#TopLevelRules) (SHFB). + This tool’s handling of `` tags is based on the [design document]( https://github.com/dotnet/csharplang/blob/812e220fe2b964d17f353cb684aa341418618b6e/proposals/inheritdoc.md) used for Roslyn's support in Visual Studio, which is in turn based on the `` support in [Sandcastle Help File Builder]( https://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm#TopLevelRules) (SHFB). 2) Add the [SauceControl.InheritDoc](https://www.nuget.org/packages/SauceControl.InheritDoc) NuGet package reference to your project. @@ -20,6 +20,15 @@ How to Use It The XML docs will be post-processed automatically with each non-debug build, whether you use Visual Studio, dotnet CLI, or anything else that hosts the MSBuild engine. +Additional Features +------------------- + +* Updates the contents of inherited docs to replace `param` and `typeparam` names that changed in the inheriting type or member. + +* Supports trimming your published XML doc files of any types or members not publicly visible in your API. + +* Validates your usage of `` and warns you if no documentation exists or if your `cref`s or `path`s are incorrect. + How it Works ------------ @@ -309,4 +318,4 @@ When it runs, `InheritDocTask` will log a success message to the build output fo InheritDocTask replaced 55 of 55 inheritdoc tags and removed 60 non-public member docs in /path/to/MyProject.xml ``` -If you don't see the message(s), it didn't run for some reason. Check the detailed output from MSBuild (e.g. `dotnet build -v detailed`) and look for `InheritDoc` in the logs for clues. Issue reports are, of course, welcome with good repro steps. +If you don't see the message(s), it didn't run for some reason. Check the detailed output from MSBuild (e.g. `dotnet build -v detailed`) or use the [MSBuild Log Viewer](https://msbuildlog.com/) and look for `InheritDoc` in the logs for clues. Issue reports are, of course, welcome with good repro steps. diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 2bc973b..7aeb115 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -15,10 +15,6 @@ snupkg - - - - diff --git a/src/InheritDoc/CecilExtensions.cs b/src/InheritDoc/CecilExtensions.cs index 8ab176d..79422d1 100644 --- a/src/InheritDoc/CecilExtensions.cs +++ b/src/InheritDoc/CecilExtensions.cs @@ -407,7 +407,7 @@ static bool isCompatibleName(AssemblyNameReference name, AssemblyNameReference c public void Dispose() { foreach (var asm in cache.Values) - asm.Dispose(); + asm?.Dispose(); cache.Clear(); } diff --git a/src/InheritDoc/readme.md b/src/InheritDoc/readme.md index 4cefdcd..babf9b9 100644 --- a/src/InheritDoc/readme.md +++ b/src/InheritDoc/readme.md @@ -1,14 +1,14 @@ InheritDoc ========== -This [MSBuild Task]( https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-tasks) automatically replaces `` tags in your .NET XML documentation with the actual inherited docs. By integrating with MSBuild, this tool has access to the exact arguments passed to the compiler -- including all assembly references -- making it both simpler and more capable than other documentation post-processing tools. As it processes `` elements, it is able to accurately resolve base types whether they come from the target framework, referenced NuGet packages, or project references. This allows intelligent mapping of documentation from base types and members to yours. For example, it can identify when you change the name of a method parameter from the base type’s definition and update the documentation accordingly. It can also remove documentation for non-public types/members to reduce the size of your published XML docs. +This [MSBuild Task]( https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-tasks) automatically replaces `` tags in your .NET XML documentation with the actual inherited docs. How to Use It ------------- 1) Add some `` tags to your XML documentation comments. - This tool’s handling of `` tags is based on the draft [design document]( https://github.com/dotnet/csharplang/blob/812e220fe2b964d17f353cb684aa341418618b6e/proposals/inheritdoc.md) used for Roslyn's support in Visual Studio, which is in turn based on the `` support in [Sandcastle Help File Builder]( https://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm#TopLevelRules) (SHFB). + This tool’s handling of `` tags is based on the [design document]( https://github.com/dotnet/csharplang/blob/812e220fe2b964d17f353cb684aa341418618b6e/proposals/inheritdoc.md) used for Roslyn's support in Visual Studio, which is in turn based on the `` support in [Sandcastle Help File Builder]( https://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm#TopLevelRules) (SHFB). 2) Add the [SauceControl.InheritDoc](https://www.nuget.org/packages/SauceControl.InheritDoc) NuGet package reference to your project. @@ -18,4 +18,13 @@ How to Use It The XML docs will be post-processed automatically with each non-debug build, whether you use Visual Studio, dotnet CLI, or anything else that hosts the MSBuild engine. +Additional Features +------------------- + +* Updates the contents of inherited docs to replace `param` and `typeparam` names that changed in the inheriting type or member. + +* Supports trimming your published XML doc files of any types or members not publicly visible in your API. + +* Validates your usage of `` and warns you if no documentation exists or if your `cref`s or `path`s are incorrect. + For more details and examples, see the [project home page](https://github.com/saucecontrol/InheritDoc)