You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: readme.md
+49-6Lines changed: 49 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,14 +3,14 @@
3
3
InheritDoc
4
4
==========
5
5
6
-
This [MSBuild Task](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-tasks) automatically replaces `<inheritdoc />` 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 `<inheritdoc />` elements, it is able to more accurately resolve base types whether they come from the target framework, referenced NuGet packages, or project references. This means it can be more clever about mapping 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.
6
+
This [MSBuild Task](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-tasks) automatically replaces `<inheritdoc />` 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 `<inheritdoc />` 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.
7
7
8
8
How to Use It
9
9
-------------
10
10
11
11
1) Add some `<inheritdoc />` tags to your XML documentation comments.
12
12
13
-
This tool’s handling of `<inheritdoc />` tags is based on the draft [design document](https://github.com/dotnet/csharplang/blob/812e220fe2b964d17f353cb684aa341418618b6e/proposals/inheritdoc.md) used for the new prototype Roslyn support, which is in turn based on the `<inheritdoc />` support in [Sandcastle Help File Builder](https://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm#TopLevelRules) (SHFB).
13
+
This tool’s handling of `<inheritdoc />` 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 `<inheritdoc />` support in [Sandcastle Help File Builder](https://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm#TopLevelRules) (SHFB).
14
14
15
15
2) Add the [SauceControl.InheritDoc](https://www.nuget.org/packages/SauceControl.InheritDoc) NuGet package reference to your project.
16
16
@@ -30,6 +30,11 @@ This enhances the new support for `<inheritdoc />` in Roslyn (available starting
@@ -150,8 +155,10 @@ Once processed, the output XML documentation will look like this (results abbrev
150
155
</member>
151
156
```
152
157
153
-
Advanced Examples
154
-
-----------------
158
+
</details>
159
+
160
+
<details>
161
+
<summary>Namespace Documentation</summary>
155
162
156
163
Although the .NET compilers [don't allow](https://github.com/dotnet/csharplang/issues/315) adding namespace documentation comments, some tools (including SHFB) have a [convention](https://stackoverflow.com/a/52381674/4926931) for declaring them in code. InheritDoc follows this convention.
157
164
@@ -173,6 +180,10 @@ Will output:
173
180
</member>
174
181
```
175
182
183
+
</details>
184
+
185
+
<details>
186
+
<summary>Explicit Inheritance</summary>
176
187
177
188
InheritDoc also supports the `path` attribute defined in the Roslyn draft design doc, which is analogous to the `select` attribute in SHFB.
178
189
@@ -198,12 +209,14 @@ Outputs:
198
209
199
210
Notice the `param` element for `message` was excluded automatically because there was no matching parameter on the target constructor, however with a nested `<inheritdoc />` and a custom selector, we were able to extract the contents from that `param` element into a new one with the correct name.
200
211
212
+
</details>
213
+
201
214
Configuration
202
215
-------------
203
216
204
217
#### Enabling/Disabling InheritDoc
205
218
206
-
InheritDoc is enabled by default for all normal builds. It can be disabled by setting the `InheritDocEnabled` MSBuild property in your project. This may be used if you wish to skip the overhead of running InheritDoc on debug builds, for example.
219
+
InheritDoc is enabled by default for all non-debug builds. It can be enabled or disabled explicitly by setting the `InheritDocEnabled` MSBuild property in your project.
@@ -263,6 +276,30 @@ Warnings can be selectively disabled with the MSBuild standard `NoWarn` property
263
276
|IDT003| May indicate you used `<inheritdoc />` on a type/member with no identifiable base. You may correct this warning by using the `cref` attribute to identify the base explicitly. |
264
277
|IDT004| May indicate an incorrect XPath value in a `path` attribute or a duplicate/superfluous or self-referencing `<inheritdoc />` tag. |
265
278
279
+
#### Using InheritDoc With Multi-Targeted Projects
280
+
281
+
If you are multi-targeting using the new(er) SDK-style projects and the `TargetFrameworks` property, you must ensure that you are not generating multiple XML documentation outputs to the same file path.
282
+
283
+
If you configure the XML documentation output from the project property page in Visual Studio, you may end up with something like:
The above configuration will create a single `MyProject.xml` file in your project root for all target frameworks and all build configurations. Worse, since MSBuild builds multiple target framework outputs in parallel, you may create a race condition for access to that file.
292
+
293
+
The simpler configuration, supported in all .NET Core SDK versions, is:
This will automatically name your XML file the same as the assembly name and will create it in the correct `obj` folder alongside the assembly.
302
+
266
303
Known Issues
267
304
------------
268
305
@@ -288,4 +325,10 @@ If this displeases you, you may register your discontent by commenting on the [a
288
325
Troubleshooting
289
326
---------------
290
327
291
-
When it runs, `InheritDocTask` will log a success message to the build output, telling you what it did. If you don't see the message, 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.
328
+
When it runs, `InheritDocTask` will log a success message to the build output for each processed file, telling you what it did. For example:
329
+
330
+
```
331
+
InheritDocTask replaced 55 of 55 inheritdoc tags and removed 60 non-public member docs in /path/to/MyProject.xml
332
+
```
333
+
334
+
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.
0 commit comments