This project is read-only.
3
Vote

Improve XML docs

description

There was a thread about this, but I think it warrants a place to vote on it. I think a small but high-impact feature would be improving the current documentation capabilities.

Good practice dictates that you thoroughly document all of the public-facing surface area of a class. Yet XML docs almost fight you in trying to do so- XML docs are very verbose, annoying to edit, take up a lot of screen real estate, and the XML (and associated annoyances like escaping) distracts from the actual content you're trying to get across.

My personal preference would be supporting JavaDoc syntax in addition to the existing XML docs. This would allow much more concise and to the point documentation without lots of unnecessary ceremony.
/** Someone using the application */
class User
{
    /** The age of the person. */
    pubic int Age {get; private set;}

    /** Forces the user to say some words.
      * @param words The words the user must say. */
    public void Speak(String words)
    {
        Console.WriteLine(words);
    }
}
This isn't the only possible solution, of course. Other ideas are welcome.

comments

SSL wrote May 29, 2014 at 1:50 AM

That's a breaking change.

XML doc comments are already allowed to appear in Javadoc-style /** comments, but still require XML tags.

Instead, you can reduce the overhead by combining things into one line:
    ///<summary>This is a sample doc comment.</summary>

MgSam wrote May 29, 2014 at 1:57 PM

@SSL Interesting- I wasn't aware of that feature, and I've never actually seen it used before. It's hardly a show-stopper though; there are multitudes of other ways you could delimit some sort of special comment; /*/, for example.

As to your suggestion, I think you're missing the point. In my example above standard XML docs on the method would look like this:
/// <summary>
/// Forces the user to say some words.
/// </summary>
/// <param name="words">The words the user must say.</param>
Not counting the triple slashes or newlines, this requires 42 characters of extra syntax to form the XML tags. The JavaDoc solution (again not counting slashes, stars or newlines) requires only 6 characters of extra syntax. That is an 86% savings in characters. That means more productivity in writing, editing, and reading documentation, any way you look at it.

JanKucera wrote May 29, 2014 at 4:10 PM

Leaving aside that you won't be allowed to begin comment e.g. with @param, how would you support other elements, like remarks, see, returns, example - keep them as xml elements? What about custom xml elements?

MgSam wrote May 29, 2014 at 6:57 PM

@JanKucera Why can't you begin a comment with @param? Any element is prefixed by an @ sign; so they would be @returns, @remarks, etc. The end of an element is delimited by the line break.

sharwell wrote May 29, 2014 at 7:47 PM

I feel that this proposal only offers a solution to one problem with the documentation syntax. The following remain limitations to commenting in the language as a whole. Any real modification to the comment syntax should strive to address all of the following items.
  1. Semantic references to specific code elements (e.g. <see cref="IntPtr"/> or <paramref name="arg1"/> are only allowed within documentation comments. Refactoring operations that rename code elements are able to locate these references, but only in that context. There are many other contexts where a user wants to mention a specific code element by name (such as comments within a method body), and the ability to indicate a semantic link to the correct element would dramatically improve the ability of refactoring tools to accurately rename code elements. Furthermore, some code elements, e.g. local variables, cannot be semantically referenced in a comment under the current syntax.
  2. The syntax for documentation comments as a whole is unwieldy. Some of this situation could be remedied through an editor behavior that understands the overall syntax of a documentation comment. For example, the editor could show the following without actually inserting any of the text into the file.
    /// <summary>
    ///
    /// </summary>
    /// <returns>
    ///
    /// </returns>
    
    If the caret were located on the empty line in the summary section, 1) typing a character would automatically add the summary tags to the document and 2) pressing the down arrow would move the caret to the empty line in the returns section.
  3. The IDE does not have the ability to show a "pretty" form of the documentation comments. Such a feature would need to be highly extensible in order to support the numerous additional features provided by SHFB (including, but not limited to, <inheritdoc/>).

JanKucera wrote May 29, 2014 at 7:49 PM

Oh I see, you use the xpath attribute designator for elements, got confused by this. How do you write elements with multiple attributes? (like include)
Why can't you begin a comment with @param?
I meant a comment where you didn't mean to begin an element, just a text with @ (which can happen if parameter names in your method need to be prefixed with @).
The end of an element is delimited by the line break.
Now that's quite disturbing.
  • How would you write multiline text in elements? I often have multiple lines, mostly in remark.
  • How would you write inline elements? Just the regular use of see element, paramref etc.

MgSam wrote May 29, 2014 at 8:55 PM

@sharwell I agree with 1), this is another sore point with the current comment system. However, without making the cost of the feature explode, I 'd say you should only allowed to refer to names available in the same scope at your comment. I cringe every time I see <see cref="T:System.Microsoft.Namespace.ReallyCoolType"/>. I like the backtick syntax.

For #2, your proposal only makes XML docs a little bit easier to write. You need to read them as well as write them. And right now reading them is painful chore.

@JanKucera I'm not sure how JavaDocs deal with that (if they do), but I could imagine some kind of nesting syntax. @include(@file myfile.doc, @path mypath). I may be wrong about the newline being the closing delimiter. It probably makes more sense for the next non-nested @ encountered to be the closing delimiter of a tag, with whitespace being trimmed from the parsed text.

Again, I should point out I'm not claiming to have all the questions answered or that the syntax I proposed is the "right" one. I created this issue so people could vote on the need to have a better documentation system, whatever form that might ultimately take.

JanKucera wrote May 29, 2014 at 9:07 PM

sharwell:
3.The IDE does not have the ability to show a "pretty" form of the documentation comments. Such a feature would need to be highly extensible in order to support the numerous additional features provided by SHFB (including, but not limited to, <inheritdoc/>).
You might be able to find VS extensions for this, e.g.
http://visualstudiogallery.msdn.microsoft.com/668a65b5-2468-4afa-b78d-8c369850e2b2

sharwell wrote May 29, 2014 at 9:26 PM

MgSam:
For #2, your proposal only makes XML docs a little bit easier to write. You need to read them as well as write them. And right now reading them is painful chore.
I'm hoping to implement this in an extension. Here is one such issue:

https://github.com/tunnelvisionlabs/SHFB/issues/16

In a similar manner, <see langword="null"/> could be collapsed to null, and <see cref="Action"/> could be collapsed to a syntax-highlighted word Action. If the editor doesn't allow syntax highlighting of the preview text for a collapsed region, it would also be possible to collapse <see cref=" to just < and "/> to >.