Any plans to use the Xml comments as the source for the generated markdown?

[StingyJack]

I'd like to use this, but dont want to have to change everything over to a special comment format that wont work with the built in VS features. Would you take pull requests that add this functionality or is that something you arent willing to entertain?

[dadhi]

@StingyJack I don't think it will work. Could you describe your idea in detail?

[StingyJack]

.net languages have had xml comments that can be placed before a type or member since like netfx1 or netfx2. They look like this for c#...

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass {}

That is a really trivial example, they can be more complex and detailed.

/// <summary>
/// Initializes a new instance of the <see cref="CsExtraction" /> class.
/// </summary>
/// <param name="metadataReferences"></param>
/// <param name="compilationTargets">The compilation targets.</param>
/// <param name="namespaces">The namespaces.</param>
/// <param name="filePath">The file path.</param>
/// <remarks> add some important notes in here </remarks>
/// <example>
///     var ce = new CsExtraction(....etc)
/// </example>
public CsExtraction(IEnumerable<MetadataReference> metadataReferences, IEnumerable<SyntaxTree> compilationTargets, IEnumerable<string> namespaces, string filePath)

To add them for a member you can type a triple forward slash before a type or member /// and VS will add the appropriate elements. Tools like GhostDoc will even try to create meaningful summaries.

If these are present in the code and the documentation file generation is enabled, then when the solution is built they are extracted by visual studio/msbuild and placed in a .XML file in the same place the dll or exe is placed. These are the things that power the intellisense and tooltip descriptions for functions when you are typing. You can even make VS fail a compilation if any of these are missing on any public api surface. At my current workplace, there are probably several hundred thousand if not millions of these kinds of comments and more are added every day.

I think its safe to say that most .net developers will prefer maintaining the resulting documentation in markdown format more than we would for full html or xml. I like the idea you have here, but as this requires special //md comments, we would either have to choose to do both and repeat the comment contents or forego the existing documentation mechanism. I dont think anyone will want (or be able to justify) having two comment blocks per type/member, and we wouldnt want to give up the benefits of the existing documentation system. The suggestion is to address that gap by having the CsToMd tool ingest these xml comments as the source in conjunction with or as an alternative to the //md

[dadhi]

@StingyJack

Thanks for explaining. I know what xml-docs are, those for the API documentation and there are plenty of tools to work with them including the msbuild (as you said). This extension/cli-tool solves the different problem of creating the User's guide, Quick start, etc. arbitrary documentation with inclusion of the compile-able/runnable examples and snippets. In this approach the snippets formed by the normal unit tests and the rich documentation build from the special comments around them. Those comments may have arbitrary structure and interleave the tests or any additional code classes, metgods, be inside the methods, etc. which is not possible for the xml-docs. AFAIK the similar approach is used by the Literate programming (check wikipedia). So you can compile, run, debug your tests (snippets) as usual part of your build system and additionally generate md doc with TOC, text and links. Look at the the DryIoc docs for reference https://github.com/dadhi/DryIoc/blob/master/docs/DryIoc.Docs/Home.md#getting-started. Navigate the repo to see how md docs folder is just the normal test project otherwise.

Overall I have come up with this approach as the laziest way of creating the docs and automatically keeping the samples up-to-date. There are much more sophisticated platforms for that, like readthedocs, etc. But again, I don't have enough time to cook them in my OSS projects and I don't like writing the documentation in general. But writing the tests is another thing and makes the mental trick for me :-)