Lightweight documentation comment syntax

[nanoant]

I wish I had such a lightweight way to document my C# code, that does not require introducing extra additional content/lines/syntax that serve to (computer) documentation generator, but not me (human developer), where I don't need to repeat myself and finally something that does not require extra effort to label content for documentation generator and does not cause eye-strain, e.g.:

// Represents canvas you can paint on.
//
// Example:
//   Canvas canvas;
//   canvas.Fill(rect);
//
public class Canvas {
    // Available colors
    public enum Color {
        Green, // Color of the grass
        Blue   // Color of the ocean
    }
    // Available shades
    public enum Shade {
        Dark, // As when it is a night
        Light // As when it is a day
    }
    // Fills given `Rectangle` with given `Color`
    public void Fill(
        Rect rect,   // Rectangle to fill
        Color color, // Color of the filling
        Shade shade  // Shade of the `Color` above
    ) {
        // ...
    }
}

This is what I have to write today using XML documentation:

/// <summary>
/// Represents canvas you can paint on
/// </summary>
/// <example> 
/// <code>
/// Canvas canvas;
/// canvas.Fill(rect);
/// </code>
/// </example>
public class Canvas {
    /// <summary>
    /// Available colors
    /// </summary>
    public enum Color {
        /// <summary>
        /// Color of the grass
        /// </summary>
        Green,
        /// <summary>
        /// Color of the ocean
        /// </summary>
        Blue
    }
    /// <summary>
    /// Available shades
    /// </summary>
    public enum Shade {
        /// <summary>
        /// As when it is a night
        /// </summary>
        Dark,
        /// <summary>
        /// As when it is a day
        /// </summary>
        Light
    }
    /// <summary>
    /// Fills given <see cref="Rectangle"/> with given <see cref="Color"/>
    /// </summary>
    /// <param name="rect">Rectangle to fill</param>
    /// <param name="color">Color of the filling</param>
    /// <param name="shade">Shade of the <see cref="Color"/> above</param>
    public void Fill(Rect rect, Color color, Shade shade) {
        // ...
    }
}

My 2 major issues with XML documentation in C# are:

1. Forcing the use of <summary> that creates lot of additional text to parse for human eyes and lot of additional vertical source code volume (but not content as it carries no information whatsoever), that prevents having as much as possible relevant content/information on the screen, and that all for only reason is to make documentation generator know where the summary starts and ends.

   This can be achieved as well by simple convention that 1st paragraph is a summary, and is separated from the rest by one blank line, and additionally allowing placing documentation for enums, variables, etc. one the same line after the declaration.

2. Forcing the repetition when describing method/function arguments with <param name="...">...

   As above, we can add the argument documentation on the same line after declaration. We don't need to put the argument name twice in two distinct places.

We are humans not machines, HTML / XML was not meant to be read by humans, but to be parsed by the computer and formatted and then presented to the human in a readable fashion. Nevertheless, working everyday with C# code, C# developers are forced to parse raw XML syntax, even they don't want to, even when they don't need to, because these comments are there in front of their eyes.

C# is nice language, and as every high level language is must serve human developers and be deterministic for the machine compiler. XML documentation on other hand is certainly deterministic, but IMHO does not serve human developers.

Remarks

This issue was created as a direct follow-up for closed Roslyn issue: Feature Request: Lighter syntax for doc comments that apparently is NOT compiler issue, but language spec issue, therefore the correct place to discuss it is here.

Other issues that are worth to mention and link are:

1. Documentation Block without XML (Missing from Spec) that postulates removal of <summary> requirement like it is now in F#, or (alternatively?) fixing this in the Spec
2. Using YAML + Markdown format in documentation comments
3. Use Markdown in Documentation Comments to Reference Source Code

[HaloFour]

The purpose of XML docs is to drive the tools that generate external documentation which would be read by human developers, as well as to drive tooling within the IDE. It would seem that a computer-readable format would be better suited to that task than some other arbitrary format. You're always free to write free-form documentation using whatever syntax you'd prefer, and the compiler accepts your use case examples above without complaint. You could even write a Roslyn-based tool that would extract those comments into another form like a Markdown document if you so chose.

I will agree that reading XML documentation within the IDE is a bit of a chore. I'd like to see tooling within the IDE that could both render it inline in a more attractive manner as well as hide it completely when it's not relevant. To me the bigger problem is that XML documentation (or Javadoc or Scaladoc or Python docstring or whatever) eats up a huge amount of real estate, period, XML or not. A decent number of the Java libs I work with seem to be 80% javadoc comments and it's a struggle to find code at all.

[DavidArno]

Make your code more self-explanatory and the comments can go completely:

public class Canvas 
{
    public enum Color { Grass, Ocean }
    public enum ColorShade { Night, Day }

    public void FillRectangle(Rectangle rectangle, Color color, ColorShade shade) 
    {
        // ...
    }
}

And with all that noise gone, suddenly the code is so much clearer and easier to read and understand.

[sharwell]

Here's my work-in-progress for a proposal in this space:
https://gist.github.com/sharwell/ab7a6ccab745c7e0a5b8662104e79735

[svick]

@HaloFour

It would seem that a computer-readable format would be better suited to that task than some other arbitrary format.

You can have a format that's both human-readable and computer-readable. For example, I think Markdown does a good job of that for simple markup. A similar approach could be applied here.

To me the bigger problem is that XML documentation (or Javadoc or Scaladoc or Python docstring or whatever) eats up a huge amount of real estate, period, XML or not.

For comments that contain a lot of noise, a simpler format will help. For comments that are legitimately long, I think there are two options:

1. Tooling to hide them. VS already can do this. Though you're going to have a much worse experience if you're e.g. viewing code on GitHub.
2. Move them to external files. This approach has its own set of problems.

@DavidArno

Make your code more self-explanatory and the comments can go completely:

That might help for this simple example. But most code isn't like that and documentation comments are invaluable there.

[nanoant]

@sharwell: Thanks for mentioning your proposal. That's a really great effort, and at the first glance it is far more readable. Also I am in favor of using param: and return: since it is enough for both human beings and computers to understand what we are just trying to do describe there.

Btw. Many of the alternative XML proposals I have seen are usually trading the XML syntax for something more simple. But I ask myself - do we really need that extra syntax at all if our intentions are clear looking at the text?

For example, isn't the summary/brief always first paragraph when we write documentation for the method? Isn't then paragraph break enough the separate brief from the rest. Why would someone want a brief that has few paragraphs?

Another example, if `rect` is a param to the function that we are just documenting, or `Canvas` is some class that exists in the code in the current context, can the documentation generator that is coupled with a compiler figure this by itself and generate proper semantics and/or link in the documentation?

IMHO if the documentation generator (embedded in the compiler) cannot infer our intentions (documentation semantics) it is very likely were writing something unclear that would not be good documentation anyways.

[juliusfriedman]

@sharwell, I like your abbreviated approach just wish that it would be able to be converted to xml doc which is already supported, XSLT already supports this and I feel like it would be trivial to implement a transform to achieve this; thus no matter what the shortened syntax ends up being we should support the notion of transforming that syntax back into XML.

That is one place where the existing XML doc is hard to beat, when you have to transform it to show it somewhere....

[YairHalberstadt]

@juliusfriedman
That could probably be implemented pretty easily as a Roslyn code fix.

[sharwell]

I already implemented most of it via a code fix. 😁

More specifically, I implemented support for things within a section but I still need to implement the outer section support.

https://github.com/DotNetAnalyzers/DocumentationAnalyzers/blob/master/docs/DOC900.md

[DavidArno]

@svick,

Make your code more self-explanatory and the comments can go completely:

That might help for this simple example. But most code isn't like that and documentation comments are invaluable there.

I completely disagree. I have never come across code that is, on balance, enhanced by documentation comments. They are pretty much guaranteed to (a) be really poor quality documentation and (b) make the code really hard to read. The benefits of the documentation they do offer is outweighed by the difficulty they bring to reading the code itself. Though IDE's that render comments in pale colours to help the eye focus on the code can help, stripping out the comments and keeping the documentation separate helps far more.

A perfect example of this is with the modern docs for .NET. Gone are nonsense comments like

/// <summary>
/// Gets a <see cref="Foo"/> instance.
/// </summary>
/// <value>
/// A <see cref="Foo"/> instance representing a default Foo.
/// </value>
public Foo Foo => new Foo();

to be replaced with quality documentation written by folk who are good at documenting. So we might expect detailed examples, descriptions of edge cases, etc etc, not inane "this property gets and sets its field" "documentation".

But the downvotes show I've picked the wrong forum here to point out the emperor is not actually wearing clothes... 🙊

[sharwell]

@DavidArno This topic is about the experience for users who have already chosen to write documentation comments. Replies challenging the premise are off-topic.

[DavidArno]

@sharwell, that makes sense. I’ll duck out in that case. 👍

[dsaf]

Wouldn't C# become a graveyard of dead markup/transport languages? We barely dodged the JSON bullet. Please support this via IDE only.

[svick]

@dsaf

Wouldn't C# become a graveyard of dead markup/transport languages? We barely dodged the JSON bullet.

If C# had JSON support and JSON was replaced with something new, then that JSON support would become useless.

But if C# had Markdown-based documentation comments and Markdown was replaced with something new, then those documentation comments would still be useful.

This is not about chasing what's popular right now. It's about improving a lacking aspect of C#. And since doing that requires some kind of markup language, it probably makes sense to start with a markup language that's currently popular.

[nanoant]

@DavidArno

A perfect example of this is with the modern docs for .NET. Gone are nonsense comments like

This is a perfect example of what I encounter often. However, until I realize that there is no information/content I need to put additional effort to peal off XML documentation tags, just to realize what's left carries no additional message to what was already said in the source code.

My impression is that some of the developers that are forced by project rules (e.g. forcing putting documentation to every public entity/class/enum/etc.) feel safe putting random XML tags to calm the rule down, despite that renders the docs pretty useless.

So IMHO XML documentation in the end prevents to easily spot the places where documentation is lacking. I am okay to have XML documentation as an output of the compilation process, but not XML within the source code.

And to be clear, I completely agree with you that the code should be self-explanatory in the first place. It is just my example that is super-trivial and completely unrealistic that probably violates that.

[marksmeltzer]

Don't any of you write libraries that other developers consume? (Or even that you consume from other projects?) The code documentation is invaluable in that context. The trival "this property gets and sets the field" has exactly this value: it lets developers know it is an O(1) operation, whether it is thread-safe (and in what way), what the side effects are (e.g. only modifies the one field), etc. The fact that 80% of properties might be simple auto-properties (or could be) and thus have the same documentation template is a good thing. It means developers consuming the API can quickly recognize them as instances of the normal case. I always have the decompiled source code one control click away with my VS settings, but I really prefer to have the intellisence prompts remind me about the conventions. My main gripe against the fancy doc capabilities is that VS intellisence doesn't support them. Remarks would be great if VS showed them in the intellisence experience. Or if the F1 help system was tied into some nuget enabled HTML documentation for the library. Since intellisence is so limited in it's current form (haven't tried 19 yet), I put everything that should go in Remarks as sub-content in the Summary section. So, my summary sections can be long, but they are also very informative. So whatever fancy new capabilities are added to support writing better documentation also need to be augmented with reciprocal enhancements to the in-editor intellisence experience in order to actually be worth a damn. Regards, Regards,

…

________________________________ From: Adam Strzelecki <[email protected]> Sent: Sunday, April 7, 2019 3:50:26 AM To: dotnet/csharplang Cc: Subscribed Subject: Re: [dotnet/csharplang] Lightweight documentation comment syntax (#2394) @DavidArno<https://github.com/DavidArno> A perfect example of this is with the modern docs for .NET. Gone are nonsense comments like This is a perfect example of what I encounter often. However, until I realize that there is no information/content I need to put additional effort to peal off XML documentation tags, just to realize what's left carries no additional message to what was already said in the source code. My impression is that some of developers that are forced by project rules (e.g. forcing putting documentation to every public entity/class/enum/etc.) feel safe putting random XML tags to calm the rule down, despite that renders the docs pretty useless. So IMHO XML documentation in the end prevents to easily spot the places where documentation is lacking. I am okay to have XML documentation as an output of the compilation process, but not XML within the source code. And to be clear, I completely agree with you that the code should be self-explanatory in the first place. It is just my example that is super-trivial and completely unrealistic that probably violates that. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub<#2394 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ASRWY9EuslHGw3JdbVsZ-LYHTZeEqksyks5vec1ygaJpZM4ce7DY>.

[nanoant]

There already are millions of lines of code with these XML comments, and instead of introducing a new format which will only benefit those who start using it, if the IDE were to display these XML comments in a more human-friendly form, all developers will get an immediate benefit.

Why it would be not possible for existing projects to migrate to the new syntax?

And why so many language improvements introducing absolutely no new functionality, but exclusively just convenient and concise syntax were ok for several last years for C# lang team, but apparently touching XmlDoc thing is such a drag?

[CyrusNajmabadi]

but apparently touching XmlDoc thing is such a drag?

Who said taht @nanoant ?

[nanoant]

Who said taht @nanoant ?

Well I guess no one. And that's the point. But hey, let's get some popcorn & soda soon and enjoy 3 yr anniversary of @sharwell's excellent YAML-like proposal contoured by the dead silence of the rest of project maintainers.

Oh and I forgot we have soon also 7 yrs anniversary of dotnet/roslyn#85 which was the original issue closed as a non-compiler issue.

In meantime we can also enjoy watching last Azure DevOps XAML builds being switched to YAML, despite one doesn't need to touch such definitions more than few times a year. Yet parsing XML with one's own eyes everyday is still fine. And finally cherry on the cake - a modest proposal to have "XmlDoc" renderer hiding XML tags as a compromise deal. 🙄

[CyrusNajmabadi]

Well I guess no one. And that's the point. But hey, let's get some popcorn & soda soon and enjoy 3 yr anniversary of sharwell's excellent YAML-like proposal contoured by the dead silence of the rest of project maintainers.

I don't get your point. There are hundreds of suggestions we haven't moved on in this time. We are a small team completely full with work. I'm sorry this particular one isn't moving forward at the rate you'd like, but there's only so much we can do.

Oh and I forgot we have soon also 7 yrs anniversary of dotnet/roslyn#85 which was the original issue closed as a non-compiler issue.

I've been working with C# since before it was called C# :) There are tons of things i've wanted as well that haven't come to pass.

And finally cherry on the cake - a modest proposal to have "XmlDoc" renderer hiding XML tags as a compromise deal.

None of these proposals are modest. They require a lot of time and effort across a small team already fully loaded with work. I'm sorry we're not getting things in in the order you want, but no matter what set of work we pick that's always going to be teh case.

And we're not going to just prioritize things by age as that just means more important current stuff is itself pushed out for less important things.

[nanoant]

And we're not going to just prioritize things by age as that just means more important current stuff is itself pushed out for less important things.

I see... so this has been less important than all the features implemented in last 7yrs in C# 7-10. Particularly looking there at: https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-version-history

I must be then an horrible outlier that I don't enjoy XmlDoc so much as the others and I am not adapting every new language feature introduced instead. But I accept that. Also I accept that each of these features has probably some backing issue here with at least an order of magnitude more C# developers fighting for it and this is how the priorities are settled. I am just too lazy to find these issues. I guess it is high time to duck out for me.

[CyrusNajmabadi]

I see... so this has been less important than all the features implemented in last 7yrs in C# 7-10

Correct. Our evaluation of the features and the effort involved led to the resulting set of work being decided on.

and this is how the priorities are settled

Priorities are settled using a multitude of factors and signals. Sometimes it's based on how many devs are fighting for it. Sometimes it's based on the tremendous value provided to some particular part of the ecosystem, etc. etc.

[Gaddy]

If I can just add a few toughts :

• There is no need to modify any existing behavior, it would just be adding "if intellisense cannot find a xml comment, search for a classic comment at the end of line or on the line above.". It is already done in C++ intellisense, and in VAssist plugin for C#. So it should not be too complex?

• I honestly think that if you do a survey asking to developers if they wish that feature, they would massively answer yes, much more than most new tech features very few people use. This one is an improvement for everyone, from the very beginner (who will probably not use xml comments, and so will deny himself the ultra-useful C# intellisense quick info tooltips)

• As a reminder here is the suggest format format from the original post (with a added var):

private float myVariable; // this variable does xxxx

// Fills given `Rectangle` with given `Color`
public void Fill(
    Rect rect,   // Rectangle to fill
    Color color, // Color of the filling
    Shade shade  // Shade of the `Color` above
) {
    // ...
}

And a quote of the explanation "We are humans not machines, HTML / XML was not meant to be read by humans"

[CyrusNajmabadi]

it would just be adding "if intellisense cannot find a xml comment, search for a classic comment at the end of line or on the line above.". It is already done in C++ intellisense, and in VAssist plugin for C#.

Please open an issue over at github.com/dotnet/roslyn for this. It can be considered there.

So it should not be too complex?

It would definitely be complex. Our symbol model (delivered by the compiler) doesn't store comments that way. So we'd either need them to add that (unlikely) or we'd have to have a backchannel for this (which likely means expensively going ack to source to figure this out).

It could be done. But would need team discussion on if this is a good idea.

Rect rect, // Rectangle to fill

This is even more difficult as the comment isn't even associated with that parameter anymore :)

[Gaddy]

Thank you for your answer. Sorry I thought this topic was exactly about that, but I am not very skilled, i didn't even know what is "roslyn". If i understand well this topic was about the automatic generation of "hard" documentation, whereas my point was the generation of intellisense quick info tooltips in Visual Studio, and both work differently (?)
Sorry for the out of topic answer then.
About the comments inside the params, it is not really needed, just taking into account comments at the end of the line for variables ; and comments on the line above for methods/properties/classes would be perfect.

[bernd5]

I think Cyrus ment a field comment, not a parameter.

I would handle only comments which are directly before the member declaration.

A comment followed by multiple new lines followed by a member declaration should not be considered as a member comment.

[TahirAhmadov]

Why it would be not possible for existing projects to migrate to the new syntax?
And why so many language improvements introducing absolutely no new functionality, but exclusively just convenient and concise syntax were ok for several last years for C# lang team, but apparently touching XmlDoc thing is such a drag?

It's possible, but it's expensive and unlikely to be prioritized over development work. I think an IDE improvement would be a very cheap and easy way to instantly improve XmlDoc readability for everybody. Keep in mind that the XML format serves a purpose as others explained and making a new format do everything correctly is a big development and testing effort.

[breyed]

For perspective, C# documentation comments go back to C# version 1. C# was a much more verbose language back then. No type inference (var or shorthand new), no records, no lambdas, no generics (so lots of casting), no file-scoped namespaces, etc. Verbose comments were par for course.

Since then languages (including C#) have evolved to be leaner and more expressive, while enhancing readability. Ceremony has been cast aside to make way for better productivity.

The one readability area untouched in 22 years is the documentation comments. It's not a trivial effort, especially when you consider the work to do it right, such as IDE autocomplete support, syntax highlighting, refactoring, and code analysis, including mass conversion between styles. But then again, none of the other productivity features were trivial either. It's time that C# documentation comments got their turn.

[bugproof]

Just bring F# comments to C# please I'm tired of visual XML comments clutter :(

[Atulin]

Just my two cents, but I really enjoy documentation comment syntax in PHP, of all languages. Readable for humans, parseable for computers. Imagine something similar in C#:

/// @desc A method to do stuff and things. **Especially** things.
/// @param foo An instance of {@see MyProject.SomeNamespace.Foo}
/// @param bar The number of things to do
/// @returns `true` on success, `false` on failure
public bool DoStuff(Foo foo, int bar)
{
    //...
    return true;
}

Especially with IDE highlighting the @tags in a different colour.

[ljgermain]

One very easy change to make - which would simplify a lot of code just on its own, and would not require any radical restructuring of the way doc comments currently work - would be to automatically insert summary tags on XML-less doc comments (F# already does exactly this). That way instead of writing this:

/// <summary>
/// Doc comment text
/// </summary>

... you could just write this:

/// Doc comment text

This would save a TON of vertical space. A lot (perhaps even the majority) of my doc comments are just relatively short and concise summaries, and it would be much easier on the eyes (and on readability) if this were a thing.

Please bring F#-style comments to C#!

Edit: Case in point (summary is the most often occurring word in C# codebases by a massive margin, 23% ahead of System in second place): https://anvaka.github.io/common-words/#?lang=cs