Transform Markdown to XML doc about fsharp.formatting HOT 6 CLOSED

A few ideas for how this could work:

1. Extract the contents of the <summary> tags.
2. If all non-blank lines in the <summary> element's contents start with at least one space, then precisely one space will be stripped before the text is processed as Markdown. This allows people to use comments like /// Function documentation instead of being forced to write ///Function documentation to get the Markdown to work. (A brief non-scientific sample of live F# code that I looked at suggests that this is the most common way that people write their doc comments: with a space after the triple-slash.)
3. Any h2 markers (## in most Markdown doc comments) will be treated as starting a new section; what type of section they start will be determined from their text, case-insensitively, and with English plurals taken into account. ## Parameter or ## Parameters or ## parameter or ## parameters should all be turned into parameter declarations, for example.
4. Markdown will be turned into XMLdoc tags according to the following (incomplete) specification:
   • Text in ` (backtick) delimiters in a description, if it matches a name found elsewhere in the assembly, becomes a <see cref=""> link in XMLdoc, just as FSharp.Formatting does now. (But if it matches a parameter of "this" function (that is, the function whose /// docs are currently being processed), it becomes a <paramref> tag instead.
   • Text in [] delimeters (a Markdown link reference), if it doesn't have a destination but its text matches a name found elsewhere in the assembly, becomes a <see cref=""> link in XMLdoc, just as FSharp.Formatting does now. Parameters are not matched, allowing the text [map] to link to a function named map elsewhere in the assembly even if "this" function has a parameter named map.
   • If the current section is named "## Seealso" or "## See Also" in some form (give or take capitalization and whitespace), then links created by the two preceding rules will be turned into <seealso cref=""> tags instead of <see> tags.
   • Text in ` (backtick) delimiters that does not match a name found elsewhere will be turned into <c> tags in XMLdoc, so that it will be correctly monospaced in IDEs that care about formatting.
   • Inside a ## Parameters section, an unordered Markdown list in the following format will be turned into a list of <param> tags:

     - `foo` - first parameter
     - `baz` - second parameter
     

     This will produce <param name="foo">first parameter</param> and <param name="baz">second parameter</param>. Colons can also be used instead of - to separate parameter names from descriptions. Markup and links will be processed within parameter descriptions. Special case: an entry in that list where the parameter name is return or returns will instead turn into a <returns> tag in XMLdoc. (This special treatment of the names return and returns can be overridden by putting a backslash in front of the r of return(s), so that if some code has used the name returns for a parameter, that parameter can still be documented. This is not something I expect will be needed often, but it's good to document how to override that special treatment if needed.)
   • Any text inside a section titled ## Example or ## Sample code (or "Example code" or "Samples" or any number of possible variants of those terms) will be wrapped in an <example> tag, and indented blocks inside there will be turned into <code> tags inside the <example> tag.
   • The first paragraph of the XML comment will become the <summary> section in XMLdoc, and any further paragraphs will become the <remarks> section. However, if there is a Markdown section explicitly named ## Remarks (or "Remark" or "remarks" or "remark"), then this rule will not apply; instead, the ## Remarks section will be put into the <remarks> tag in XMLdoc, and the <summary> section in XMLdoc may contain multiple paragraphs.
   • A blank line in Markdown separates paragraphs, which will be marked up with <para> tags in XMLdoc.

That should cover most common usage scenarios. XMLdoc tags I deliberately did not cover include:

• <include>: probably not used now that source control doesn't require you to "lock" checked-out files, and I couldn't come up with a good Markdown-compatible syntax.
• <value>: I don't see a benefit to this unless you're writing OOP code. If you are, a ## Value section would probably work.
• <exception>, <typeparam>, <typeparamref>: these are just special cases of the ` (backtick)-delimited names section, which will convert the name to the appropriate tag if it refers to a parameter or type parameter of "this" function.

from fsharp.formatting.

Disclaimer: This are only some thoughts, I never found the silver bullet while thinking about this issue.

This issue is about existing tool support (especially VS), right? (I will go a bit deeper than the simple XML transformation here)

I feel the current state is quite unsatisfying because on the one hand you want to write xml docs for full IDE (and existing tool) support (even in design time!) and on the other hand you want to write simple markup...
For example the C# compiler gives you warnings if you miss to document parameters. Maybe we should connect with some Visual F# Power Tools or even the F# Compiler developers to tackle/think about this and work out a consistent format? We depend on them now, right? So this would be a circular dependency if they need to depend on us for parsing the markdown :)

The feature you are describing would be quite nice to provide a first step, because it will improve the tool-tips for library users and it will probably even "just work" for F# in design time as well (we probably need to hook our-self into msbuild to transform the xml after building for design time support).
But for C# I think VS is doing some trickery to update tool-tips without recompiling, so our magic will probably not work there...

Do we have users which depend on the current "quirk" markdown/xml combination (besides our-self of course)? We will obviously break them ...

As a summary: Implementing this would only be a start (in the right direction). We probably want to support and track all existing doc features and keep them in mind while designing this. Currently it feels like we are "abusing" the infrastructure. This feature would be a step back to the infrastructure. But in an ideal world this would be a F#/C# compiler plugin/extension. So maybe we should ask for an interface for such kind of things on the F# Compiler side?

from fsharp.formatting.

To add an example, here is a XML file that is produced by the F# compiler when building Deedle: https://onedrive.live.com/redir?resid=6DDFF5260C96E30A!353352&authkey=!ANPlwJ8yBrebO5M&ithint=file%2cxml

Ideally, we'd find all <summary> tags in the file and replace them with the corresponding C#-friendly Markdown.

This could be run as a post-build step (or something), so it is probably a separate tool that can be created (and then added as another project into F# Formatting).

from fsharp.formatting.

Also, this can use the existing Markdown parser in F# Formatting, so it is just a matter of finding the tag contents, calling the Markdown parser and then recognizing various patterns in the documents (like heading Parameters followed by a list with parameter name & description of its meaning. (And also, it would be nice to document those patterns so that we have some specification for what kind of Markdown we can write)

from fsharp.formatting.

Sample XML: https://gist.github.com/tpetricek/b9049883c63316dfd298eda2562b7537

from fsharp.formatting.

Closing this old issue (spring cleaning)

from fsharp.formatting.