Option to only emit XML doc comments for public/protected members

[jskeet]

(Apologies if this has already been raised. I did search for it, but couldn't find it.)

I use XML doc comments in Noda Time, just like most library authors do. I build the nuget package with dotnet pack, and that includes the XML doc comment file as expected. However, that XML doc comment file is much larger than it needs to be, because it contains the doc comments for all the internal and private members.

Could we have an option so that when building the XML file, it was slimmed down to only those members which are publicly accessible? This would help keep the size of the nuget package down somewhat, as well as presumably helping Visual Studio when that loads the file later to provide Intellisense. (The .xml file is twice the size of the .dll file, although I suspect it compresses rather more.)

[KristianWedberg]

As mentioned in the duplicate #28318, including private and internal members in the XML doc file risks exposing confidential information when e.g. publishing a NuGet package.

This forces us to strip all code comments from these private and internal members, which obviously makes our internal code documentation worse, including removing it from IntelliSense.

To me, this makes the priority of implementing this feature significantly higher.

[KristianWedberg]

As an alternative to stripping private and internal members from the XML file, an equally useful approach would be to add XML attributes that describes the visibility (private, public, ...) of each class, member etc.

This would make it easy to post-process the XML file, stripping out all private and internal items.

[chm-tm]

How about generating the stripped down version as part of generating reference assemblies? That version of the XML would also land in the \ref directory and should be automatically picked up by pack.

[SerratedSharp]

Another place this is a problem is internal *.resx files still generate to the documentation this means they include the original values pre-obfuscation/encryption since resx generated comments include the value of the entries.

[watsonsong]

Hi, is there any progress on this? If I need to implement an post-processor, I need open the xml and dll side by side to check the visibility. Hoping there will be an offical option.

[chm-tm]

Note that you can use the Sandcastle Help File Builder (SHFB) to extract the public set. You can even use SHFB exclusively for this task. You'll then need to ensure that the NuGet packager gets the new version of the XML comments. First class support would be nice indeed.

[pentp]

Since .NET 7 this issue is even more acute: when using GeneratedRegexAttribute it will currently include the very detailed regex description in XML docs, which can easily be tens of KBs for even relatively simple regexes.

[bkoelman]

I've been using https://github.com/saucecontrol/InheritDoc to work around this. It fixes both VS Intellisense and Docfx. Adding the NuGet package to your project is all that's needed. Because it runs as a build step, it should fix building your own NuGets too.