Documentation Conventions & Tooling?


#1

(Not sure that this is the right category; Full .NET/Mono Frameworks may be equally appropriate.)

On May 28 2014, Miguel announced that the .NET BCL Documentation was available under a creative commons license, specifically cc4. That documentation is currently present in mono’s source tree, within a Documentation directory for each assembly.

That works for now, but what of the future Core CLR effort? I do see some inline C# documentation comments, e.g. in System.Collections.Immutable, but I also see <include/> doc comments, e.g. in XPath, with no corresponding doc\XmlNodeOrder.uex file to import documentation from.

What would be nice is consensus around:

  1. Should Documentation be under the umbrella of the Core .NET Framework?
  2. If so, how should documentation be provided? Inline C# doc comments vs. relying upon <include/> and storing the documentation in separate files. (Using separate files is my personal preference…)
  3. If using separate files, the XML schema for those files (normal csc /doc format?).
  • It is my understanding that at present Microsoft uses a custom XML dialect for their BCL source, which was translated and imported into Mono’s source tree. This may or may not be a useful starting point.
  1. Guidelines on tooling to use, and inclusion of tooling into buildtools.

#2

Just to add my two cents here :slight_smile:

  1. Yes, I’d definitely say that documentation should be an integral part of the open source effort/project/repository.
  2. As you suggest, separate files would make tooling easier because it wouldn’t necessarily be tied to building the source, not to mention making custom editing tools easier.
  3. I’m not necessarily suggesting we use this, but I wonder if there’s a historic reason why both Mono and Microsoft moved away from using this format?
  4. If not mdoc (with modifications for this codebase and whatever format we end up using) … we’d definitely need something to keep the documentation in sync with the assemblies.
    • One potential argument for using the csc /doc format would be that keeping the docs in sync with code changes would be super easy, as we could just compare the delta of the nodes generated by csc to the ones in the doc repo/folder.

#3
  1. Yes,documentation should be an integral part of the open source effort.
  2. For right now, the best way to contribute is with /// comments. We’re still working out the details of how we can take submissions and provide built docs similar to what folks are used to getting on MSDN. We may ask you to contribute in a different way in the future, but we know we can make use of contributions via /// comments.
  3. /// comments are better for now.
  4. Tooling recommendations are TBD.

.NET Foundation Website | Blog | Projects | Code of Conduct