Feature Request: Lighter syntax for doc comments

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

[MadsTorgersen]

The objections are reasonable.

However I don’t see us doing this in the near future. We do not want to introduce a split between competing formats, and also this does not seem like it would rise to the top of where we want to invest.

[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.