Hey #dotnet #csharp mastodon, serious question/curiosity.
Take a look at the List.cs file at https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Collections/Generic/List.cs
Where the hell are the XML documentation tags (like <summary>)?
What sorcery is being done to remove them from code but still have them generate for intellesense?
I ask because I do my best to write the XML documentation for public facing parts of any library I write. I don't mind doing this, I like writing the docs
What I do mind is my code file being 90% XML and 10% c#.
How can I separate the two?
@aristurtle You can maintain the XML file(s) separately from the source code (though I guess you loose some comfort).
No idea what is being used in dotnet/runtime, but there is this documentation page on how you can keep the docs separately using monodoc https://www.mono-project.com/docs/tools+libraries/tools/monodoc/generating-documentation/#methods-of-generating-documentation
(Note that I've just read about it never tried it myself)
I've looked into this before and the best answer was to use the <inheritdoc /> with a cref attribute to an external file. But this has two problems (1) it forces to write XML using the fully-qualified names of members, which is annoying and
(2) that's not being done in List.cs
So what, when, where, why, and how is this done? I just really wanna clean up the massive amounts of documentation from my FOSS library source files but still provide that documentation xml in the NuGet packages.
@dost I think I may be on to something https://github.com/dotnet/runtime/blob/main/eng/intellisense.targets
Ultimately what I'm seeing is that yes, they do keep the XML documentation in a separate file and possibly just use some external editor to update it (cause no one is typing all that out by hand including the fully-qualified member names)
So it seems to be as simple as that, now to find an editor or make my own D:
Aristurtle
Andreas Gr眉nwald
Srit Mak 馃拃
Jeffrey T. Fritz
Dev