Feature Request: Lighter syntax for doc comments

[MgSam]

XML Doc comments are verbose, ugly, and annoying to write and read, even with the IDE support Visual Studio provides. There's no reason human beings should have to be manually typing or reading XML. With the language design committee starting work on C# 7.0, I'd propose taking a fresh look at how documentation could be written in C#.

JSDoc syntax is much more lightweight and easy to write and maintain. The chief problem with adding it is that the /** delimiter is already valid for XML docs (though I've never seen this used anywhere). Therefore, I'd propose a slight modification of the JSDoc syntax:

/*/ This method does foo. 
 * @param bar An important {@link Bar} parameter.
 * @returns An important integer. */
public int Foo(Bar bar) { }

class Bar { }

Note the extra slash as part of the delimiter for this new type of comment. (Open to other suggestions here).

Compare this to the verbosity of the current XML Docs:

/// <summary>This method does foo.</summary>
/// <param name="bar">An important <see cref="T:Bar"/> parameter.</param>
/// <returns>An important integer.</returns>
public int Foo(Bar bar) { }

class Bar { }

The JSDoc is much easier to both read and write. In the simple example above, it is only 115 characters, compared to 165 characters for the XML Doc, a savings of 30%. Savings like this could make an enormous difference when you consider how much documentation has to exist in a large codebase.

JSDoc reference:
http://usejsdoc.org/

Original issues on CodePlex:
https://roslyn.codeplex.com/workitem/215
https://roslyn.codeplex.com/workitem/188

Uservoice:
http://visualstudio.uservoice.com/forums/121579-visual-studio/suggestions/3987312-c-doc

[sharwell]

One of the fundamental problems with including semantic features inside of comments is people tend to only use them if they are literally trivial. In your example, the {@link Bar} syntax is already so complex that the ease relative to the XML syntax is irrelevant. People still would not use it.

There is no documentation system in existence which meets both the simplicity and expressiveness requirements for developers to feel comfortable using them and also provide the information needed by refactoring and other analysis tools. In absence of that, I believe the following would be especially helpful.

1. Provide support for Ctrl+Space even before the <see prefix is entered. For example, typing stri and then Ctrl+Space would provide code completion support to expand this to <see cref="string"/>.
2. Provide a diagnostic and code fix which recognizes Markdown syntax inside of documentation comments, and offers to convert them to XML documentation syntax. This could be further extended to recognize a subset of Javadoc (or JSDoc) syntax and convert it to the equivalent XML format automatically.

Here is a selection of other issues related to simplifying the usability of XML documentation comments without changing the syntax to something different but equally unusable.

DotNetAnalyzers/Proposals#21
DotNetAnalyzers/Proposals#22
DotNetAnalyzers/Proposals#23

[MgSam]

I strongly disagree with the assertion {@link Bar} is complex. It is no more complex than the Markdown we're using right now to write these posts. Its syntax makes perfect sense, unlike <see cref="T:Namespace.Class"/> which looks more like a magical incantation than a link.

A big part of the reason for suggesting JSDoc syntax is that it's already familiar to most developers- anyone who's ever touched Java, JavaScript, or TypeScript has probably run into it.

Furthermore, I think comparing implementations of the <see /> reference to compare complexity has low value in any case as it's a somewhat rarely used feature. Summary, parameter, and return type documentation use cases are far more common and in these use cases I think JSDoc is a clear and unambiguous winner.

I don't think IDE enhancements or analyzers are the answer- they just make the problem slightly easier to work with rather than addressing the root cause. You could write assembly with the most awesome IDE in the world- at the end of the day it would still be hard to read and reason about. The same rings true for XML which humans are forced to read and write.

[sharwell]

My claim regarding the complexity of the Javadoc syntax is based on a general observation that developers working on Java projects still do not use them. If Java developers won't use them, why would .NET developers? While there are exceptions to this in the Java world, there are also exceptions (like me) in the .NET world.

Keeping in mind that there are many unresolved issues surrounding this, one example of a simpl_er_ syntax for a semantic reference would be:

`expression`

where expression generally follows the rules of a nameof expression at the same location. In addition to the supported nameof expressions, it would allow a parameter list in order to to reference a particular method overload. It would also allow the unbound generic type syntax from a typeof expression.

Comments supporting this syntax could then be allowed at any location in the source code to ensure that comments containing descriptions of local variables preserve the same semantic expressiveness as documentation comments for types and members.

The most important thing to remember is IDE enhancements, diagnostics, and automatic code fixes allow developers to experiment with many potential solutions to this problem before writing one in stone (i.e. in a language specification).

PS: Your <see> example is not quite correct. If you include the T: prefix, you will face all of the same problems described for the O: prefix in #45.

[svick]

@sharwell

Keeping in mind that there are many unresolved issues surrounding this, one example of a simpl_er_ syntax for a semantic reference would be:

`expression`

where expression generally follows the rules of a nameof expression at the same location.

I like this, except that expression looks like Markdown, so I think that it should also behave that way and allow code that's not a reference. E.g. 1 + 1 would be the equivalent of <c>1 + 1</c>, while Bar would be something like <see cref="Bar"/>.

In general, I think that a combination of Javadoc-like syntax and Markdown would be both simple to use and familiar to many developers, so it makes the most sense.

[SolalPirelli]

I think the CodePlex issue 188 (based on a suggestion I originally made in the forums) is a simpler way of dealing with most cases: copy F#'s behavior, and let triple-slash comments be XML summary docs without <summary> tags, e.g.

/// Does stuff.
public static void Foo() { }

// equivalent to

/// <summary>
/// Does stuff.
/// </summary>
public static void Foo() { }

This would be a breaking change for existing comments that use three slashes without XML tags, but such comments are probably not very common, and the impact is low anyway.

[eklam]

There is no documentation system in existence which meets both the simplicity and expressiveness

Markdown:

• https://guides.github.com/features/mastering-markdown/
• http://stackoverflow.com/editing-help

[sharwell]

@eklam That covers simplicity, but out of the box it doesn't support the semantic richness that XML comments currently offer. By "expressiveness", I mean the ability to include semantic strong references to arbitrary elements of code to ensure operations like Find All References and refactoring work seamlessly in both comments and code.

[sharwell]

In case there is any doubt, everyone in this thread should know that I currently consider documentation support the leading unsolved problem in programming language design and implementation.

I do not believe the problem is unsolvable, so I'm very much in favor of:

1. Laying down as many potential solutions as possible.
2. Discussing the merits and problems associated with each potential solution, including:
   • General human support (i.e. simplicity and the "feel").
   • General IDE support (including but not limited to refactoring operations).
3. Deriving a solution meeting as many needs as possible using characteristics of the above which are best suited to solving problems instead of making new ones.

Even if I am generally against a certain approach (such as a transition to JSDoc), I would still prefer it be fully discussed.

[HaloFour]

My job function is writing libraries for other developers on other teams in my company to consume, in both C# and Java. I make it a point to write code documentation using both XML documents and JavaDoc using whatever IDE support provided by Visual Studio and IntelliJ. Honestly I find them about equally obnoxious.

First, I don't think either actually address the concerns of really writing library documentation. At best they can provide the shell; the barebones class and member listing. It's the index to the Encyclopedia. Having that to drive IntelliSense and the like is worthwhile, but beyond that I don't feel that it's the proper media for writing documentation at all. You seem to generally have two camps; those that fill in those comments and leave it at that, producing sparse and shallow documentation, and those that write novellas that significantly dwarf the code itself.

I'm not really sure what the best approach would be to solving the documentation problem. It's like trying to solve reporting or any other tedious task that nobody really wants to do anyway. I think that it should be less about writing metadata directly in the code file and more about tooling around the metadata that already exists. I could picture within the IDE some kind of support for live analysis of the code that would feed through to a visual document in which the developer could annotate using a simplified WYSIWYG editor. As new classes or members are added they would appear as skeletons within the document which the developer could then fill out.

I think that the separation of the documentation metadata from the code file itself would be beneficial in the case of having technical writers separate from the developers. There is the concern that the documentation might migrate from the live code, but that's a real problem today even when they share the same file. If the compiler or other build tools are aware of the duality of the files they could at least verify that the documented members align, like the C# compiler does today.

Lastly, I really don't understand this love of JavaDoc. I don't find it appreciably different functionally from XML documentation, although I think the latter has a few more ways to annotate things. It's marginally shorter due to the lack of XML tags, which is something that the IDE takes care of anyway. Whether the XML is uglier than JavaDoc syntax I think is more a failing of the tools in rendering the content appropriately rather than vomiting the raw metadata. But frankly, I find Java's documentation to be painfully sparse compared to that of .NET, almost as if all of it is written in JavaDoc and people have forgotten to write actual real documentation to accompany it.

Anywho, this post is more of a ramble. I'm less proposing anything and more throwing additional spaghetti at that wall. I dislike writing documentation probably as much as everyone else but I dislike being pestered about how they work even more and the best way to avoid that is to write good documentation. The vast majority of the documentation I write is not in the form of inline comments.