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.

[archer884]

I'm definitely with HaloFour on this: I'm not a huge fan of the XML documentation, but I certainly don't find it so odious that JavaDoc seems like a desirable alternative. I've enjoyed writing markdown comments in Rust lately, and I would be excited to see something like that come to C#. Having said that, I do recognize that it might be more difficult to get the depth of information we get out of the XML comments now unless there's some kind of (fragile?) black magic behind the scenes matching strings with parameter names or some such thing...

...Honestly, my IDE fills in the tags for me. It's not like writing the XML is hard. >.>

[daveaglick]

Perhaps a simple key-value syntax with Markdown support (with extensions for tables, which aren't really part of Markdown but lots of implementations have them).

Syntax

I'm thinking something along the lines of:

/// This is an *implied* summary with some `code`. It has to come before
/// any other documentation comments (otherwise it would be considered
/// part of the previously declared key).
/// Example: Here is a single-line example: `some code here`.
/// Example: And here's an example of a multi-line comment:
/// ```
/// This is my example code
/// ```
/// Remarks:
/// I can also just put my content an an **entirely** new line.
public class Foo
{
    /// Summary: This method does some stuff. We can add links (similar
    /// to <see>) with WikiMedia syntax (like GitHub pages does, even in
    /// Markdown pages): [[baz]]
    /// As with <see>, links can also be to external objects:
    /// [[System.Console.WriteLine(System.String)]]
    /// T: The current <typeparam> and <param> could be represented
    /// just as a key with the name of the param. See below for a discussion
    /// of ambiguity.
    /// baz: A `T` that indicates something *really important*.
    /// Returns: This method returns an `int`.
    public int Bar<T>(T baz, bool flag)
    {
        // ...
    }
}

Mapping to Current XML Comment Elements

The general idea here is that each comment item would be indicated simply by key: value, where key is one of Example, Remarks, Returns, Value, or Summary (which can be omitted if the summary is the first comment item).

Other current inline XML comment elements like <c>, <code>, <list>, and <para> are covered by the Markdown support. <see> is also covered by the extended support for WikiMedia style links like [[reference]] (similar to GitHub Wikis).

References to parameters and type parameters currently represented inline by <paramref> and <typeparamref> could either be handled by normal Markdown syntax like * and ** or specified using the WikiMedia syntax of [[reference]] (not sure which is better, or perhaps some extra syntax like [(reference)] or @reference should be used for local references to make it explicit that they're different from external references).

Finally, <exception>, <permission>, and <seealso> all use a cref attribute in the element to indicate what the content is referencing. These are a little trickier since a key-value syntax doesn't support additional metadata for the key. My best suggestion at this point is to put a WikiMedia-style reference in the key:

/// Exception [[NullReferenceException]]: Thrown when [(foo)] is `null`.
public void ThisMethodThrows(string foo)
{
    // ...
}

Complications

This syntax has a few complications that would have to be addressed.

Ambiguity

There would be ambiguity if the name of a parameter is the same as one of the predefined keys:

/// Remarks: Does this content correspond to the remarks
/// comment item or the `Remarks` parameter?
public void Foo(string Remarks)
{
    // ...
}

One way to remove the ambiguity would be to force a little extra syntax on parameters:

/// @Remarks: This relates to the `Remarks` parameter.
/// [(Remarks)]: Maybe this syntax is better?
/// Remarks: This is the actual pre-defined remarks content.
public void Foo(string Remarks)
{
    // ...
}

If this approach is taken, the syntax used for parameter references in the key should match what we use for parameter and other local references in the Markdown body (discussed earlier).

Custom Keys

The current XML comment syntax allows for custom documentation elements (the pre-defined set is just recommended). I think we'd also want to support custom keys with this syntax. The easiest way would just be to allow arbitrary keys and if they're not recognized as one of the pre-defined ones, they're treated as custom.

Parsing

Of course, this adds complexity to parsing. Whereas the current XML syntax can be (mostly) parsed by the native XML support in the core libraries, this new syntax would require an actual Markdown parser as well as some additional parsing work to break out the keys from the Markdown values. That would make the whole thing more complex internally, but once it's done, it's done.

[HaloFour]

XML documentation comments and JavaDoc/Rust comments are very different animals. The first only describes the metadata and leaves the presentation to the processor. The latter embeds the presentation directly in the comment. I think that it's a bad idea to explicitly tie the comments and the presentation format together. If my target isn't HTML or Markdown (and that is frequently the case) then I have to go through a fairly messy process to convert it. With XML documentation it is trivial to write a script or tool to parse the output XML and transform it into any arbitrary format.

The reality is that writing documentation sucks. People write awful documentation (or none at all) just as much in Java and JavaScript (and I bet Rust) as they do in .NET. Changing the format of the inline comments won't change this in the slightest. Good tooling (Intellisense, validation, visualization) helps but only to slightly alleviate the tedious monotony.

[daveaglick]

@HaloFour Fair enough about the separation of content and presentation, it's a good point.

I think what bothers me most about the XML comment format is that it's not really written for the person reading the code, it's written for some future processing engine to work with. I know XML is supposed to be "human readable", but every time I come across a large block of XML comments, it takes me a bit to context switch and mentally process what I'm seeing. Especially if the XML comments use nested elements like <see>, <c>, and <para>. It seems like it's addressing the 20% case (mechanically processing comments) rather than the 80% one (reading them in the source).

In regards to the concern over content vs. presentation, I agree that the two probably shouldn't be mixed. What if we used a Markdown(-like) syntax as described above, or similarly simple syntax, but put the burden of interpreting that syntax on the consumer rather than the compiler? That would simplify the compiler's job since it would no longer have to deal with Markdown and only worry about parsing out keys and values. It also wouldn't be too far off from the current scheme where the XML element content isn't presentation information per se, but contains some presentation "hints" in the form of nested elements.

[MgSam]

Agree with @daveaglick; outside of the BCL, most XML docs are read exclusively in the code itself. The current syntax is horrific for reading (and writing). The documentation syntax should be make reading and writing easier and not harder.

Also, the Javadoc-like syntax I propose in the parent post is not tied to HTML or any other output.

[HaloFour]

@daveaglick I don't feel much better looking at JavaDocs. Documentation comments, in any format, eat a lot of real estate and even in simpler form aren't really meant to be human readable. This is where I think there could be significant tooling improvements. Instead of documentation comments being a blob of text the IDE could parse them and replace them with just a formatted summary and provide simple means to navigate the details, such as formatted tool tips over the parameters, etc.

@MgSam Quite a departure from proper JavaDocs, then. If anything that would likely confuse a lot of people coming from Java, JavaScript, PHP, etc., where at least a subset of HTML is permitted.

[daveaglick]

This is where I think there could be significant tooling improvements. Instead of documentation comments being a blob of text the IDE could parse them and replace them with just a formatted summary and provide simple means to navigate the details, such as formatted tool tips over the parameters, etc.

@HaloFour So much this. Regardless of what (if any) syntax changes are made, better tooling would make them so much easier to work with.

[MgSam]

@HaloFour It seems like a relatively minor deviation to me. There are many variations of JavaDocs- JSDoc probably being the most popular. Like with any technology, you learn the differences when you start using it. It's far more difficult from someone coming from one of these other languages to adapt to C#'s XML docs than to learn about a few slight differences.

[gnat]

+1 !!!

Our internal PHP project documentation is far superior than that of our C# projects because reading XML docstrings is a pain. Just use something standardized like Doxygen. Javadoc and PHPDoc are also good implementations.

XML is bad for comments because there's so much syntactical clutter. It should look as close to a regular comment as possible (minimally annotated if needed).

There are many great things about C# but the XML docstrings are not one of them.

[helmsb]

I'd really love to see Markdown support for comments. It's simple, human readable in it's non-parsed form.

[NinoFloris]

Post from this referenced topic:

Hi guys,

I have been following the developments of the .net core initiative on foot for some time now.
As I see a lot of things have been reopened for discussion because of this huge undertaking and refactor.

One thing that I haven't seen in discussions is talk about xml documentation alternatives.
The syntax is just plain verbose and adds a huge amount of noise to what should just be documentation.

In turn an amazing amount of libraries sparingly document around key points of their public api and leave it at that.

The tools have not progressed beyond SandCastle's html generator, and it seems everyone has just taken it as something that is inherent to .Net and we all just have to deal with it no matter how crappy it is.

I propose an alternative syntax just like javadoc, phpdoc, objective-c docs, doxygen etcetera etcetera.
This allows all .net developers to use mostly existing tools (with at most minor adaptations) to create api documentation. At least this lowers the bar significantly to write docs in the first place. (and keep documentation uncollapsed in editors without burning your eyes out)

P.S.
I know Visual Studios' integrated intellisense currently relies on this syntax but it should be an easy addition to parse javadoc style comments as this could easily be integrated into roslyn, to supply this info to the correct internal structures for intellisense.

And as someone already stated, yes our php documentation is also miles ahead of our C# docs, in part because phpstorm autofills most of it. It also reads much better and it is easier spot and fix mistakes as the syntax is as close to plaintext as possible.

I'm also confident that .Net code is among the most underdocumented code I know, excluding the BCL/FCL.

[HaloFour]

@NinoFloris

And as someone already stated, yes our php documentation is also miles ahead of our C# docs, in part because phpstorm autofills most of it. It also reads much better and it is easier spot and fix mistakes as the syntax is as close to plaintext as possib

I'm sorry, I don't buy that argument at all. The two are similar enough to not matter appreciably. The appreciable differences between the syntaxes are that the XML docs require a summary tag, arguments are named and that ending tags are required, all of which are auto-generated by the IDE anyway. Beyond that they're just as easy to write. As for reading, people will be familiar with what they know. I personally find XML docs nicer because I don't have to mentally parse out the white space breaks between the tag arguments and the content. But some people have some serious grudges about angle brackets.

As for tooling, I'd agree that the story there could be improved and Sandcastle isn't very good. But at least what Roslyn spits out is regular XML. A tool can parse that using off-the-shelf tools to render into any presentation format that they wanted. Roslyn shouldn't be in the business of producing HTML or Markdown or PDFs or whatever.

[alrz]

@HaloFour

The reality is that writing documentation sucks. People write awful documentation (or none at all) just as much in Java and JavaScript (and I bet Rust) as they do in .NET. Changing the format of the inline comments won't change this in the slightest.

I think not. I'm not willing to write documentation just because I don't want some XML tags hanging around my code but markdown is natural and doesn't add much noise to it. For example.

/// Constructs a new, empty `Vec<T>`.
///
/// The vector will not allocate until elements are pushed onto it.
///
/// # Examples
///
/// ```
/// let mut vec: Vec<i32> = Vec::new();
/// ```

I don't even know how to write this in the current syntax, because every part has it's own tag and I don't bother myself to read the documentation to be able to write the documentation. Yes that sucks.

Imagine with #7655 you would get autocompletion and compiler verification which really help and it'll be more desirable to write documentation in the code and examples of usage and also would come in handy in case of refactoring etc.

[HaloFour]

@alrz

I'm not willing to write documentation just because I don't want some XML tags hanging around my code but markdown is natural and doesn't add much noise to it.

I reiterate, some people have some serious grudges about angle brackets. I despise markdown for writing documentation because of it's persnickety whitespacing rules. Want an indented paragraph followed by an indented formatted code block in a nested list? How many spaces do you need again? Which flavor of syntax do you need for the code block? The rules are ridiculous and make whitespace languages seem downright reasonable. And it's so much easier to go from XML to any arbitrary presentation format, including Markdown/HTML, than it is to go from the presentation format du jour into another.

@NinoFloris

I'm also confident that .Net code is among the most underdocumented code I know, excluding the BCL/FCL.

If @param times the times and @return the value and @throws Exception an exception count as documentation count then you're probably right. My experience is that the Java world is a lot worse.

But you know what, the more I think about this the more I think that it doesn't matter. Roslyn will happily let you stick anything you want into a comment block. An extension to VS can provide comment formatting and completion. An analyzer can provide syntax and semantics checking. You could have javadoc or markdown support in C# already without having MS be involved at all.

[gnat]

You've had ample space to write your opinion 5 times in this thread @HaloFour.

I want to hear reasoning from other people: Not just your own personal feelings.

[HaloFour]

@gnat You're right, I'll back off. And honestly, regardless of the syntax I'd love to see IDE extensions that could render them in a manner that makes them more attractive and largely out of the way. Pouring through the better documented Java libs it seems like 90% of the source is javadoc comments which is just a wall of text (often formatted for tools, not humans) that you have to parse through to find the methods and their source. Maybe it's an excuse to learn how to write VS extensions.

[daveaglick]

I'd love to see IDE extensions that could render them in a manner that makes them more attractive and largely out of the way

Totally agree. Inline with the code is the worst place of putting large blocks of comments, besides all the alternatives. They're valuable when you need them but otherwise just get in the way of fast code comprehension. I've long thought it would be great if they could be hidden/smaller/lighter until some sort of interaction like mouse-over (similar to what code lens does).

[alrz]

Hover.

I think it is not about how they look, the problem is that how should you write it.

[HaloFour]

@alrz

The built-in comment collapse is useless and the hover tooltip is still the ugly wall of unformatted text. Of course the situation with IntelliJ+Java isn't better:

Although there is a Javadoc popup which is kind of nice:

[alrz]

OK, that'd be another aspect, but I argue that what you have to write currently is more than enough.

[SergeyZhurikhin]

Of all the languages that I've seen, the model documentation in C# based on XML - the best.
Parish Roslyn his IntelliSense and keyword nameof - have become world the apogee of the documentation in the code.

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

[alrz]

@MadsTorgersen This is sad.

/// <summary>
/// Gets or sets a value indicating whether the object is active.
/// </summary>
/// <value><see langword="true" /> if the object is active; otherwise <see langword="false" />.</value>

We do not want to introduce a split between competing formats,

/// Gets or sets a value indicating whether the object is active.
/// Returns `true` if the object is active; otherwise `false`.

The doesn't introduce any particular "format", it actually removes it. Choose whatever token instead of backtick to indicate "lang word" but honestly <see langword="true" /> is just ludicrous.

It could instead get smarter about the text itself without encoding the whole thing into a particular format.

[blteblte]

XML comments on c# code makes my eyes bleed... And in fact - for everyone in our team.

In general - we try to avoid writing any comments - ever - since it makes c# code to look really dirty with huge amount of noise.

/// = ugly
/// <something = ugly
... visual studio does not help either - comments should be color-coded

[CyrusNajmabadi]

@blteblte THis issue was closed. If you have a suggestion for a better way to do things, please open an appropriate issue.

[nanoant]

@blteblte I share your pain. 😢

@MadsTorgersen Closing this issue shows that a daily comfort of the engineers working on C# source code has such a low importance for C# maintainers. Moreover argument about introducing a split is not really convincing, it is like pretending Markdown did not happen, and everyone should write directly in HTML, because this is all we got, and we cannot ask for or even imagine anything more.

I wish C# knew that 1st paragraph of documentation text is always a summary, without this "need for verbosity" forcing me wrapping most of the text with <summary>.

But yeah, we should consider ourselves lucky, C# could be much worse e.g. if we have needed to type OBJECT str PROPERTY Length in some sort of "better clear verbose" C#, instead of "ugly" short notation of str.Length 😉

@sharwell What does "Resolution-External" means in the context of this issue? Is there anything we can do to have more lightweight comments?

[CyrusNajmabadi]

@nanoant

This issue was closed. If you have a suggestion for a better way to do things, please open an appropriate issue. Note that dotnet/csharplang would likely be the right place for the conversation to happen.

[sharwell]

@nanoant there are a bunch of issues linked above for various topics related to this. Resolution external means the issues in dotnet/csharplang currently have priority.

[nanoant]

@CyrusNajmabadi @sharwell Therefore I allowed myself to create an issue on the C# lang list, hoping we can move the discussion there.