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. :+1:

[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 notifications@github.com Sent: Sunday, April 7, 2019 3:50:26 AM To: dotnet/csharplang Cc: Subscribed Subject: Re: [dotnet/csharplang] Lightweight documentation comment syntax (#2394)

@DavidArnohttps://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 GitHubhttps://github.com/dotnet/csharplang/issues/2394#issuecomment-480579229, or mute the threadhttps://github.com/notifications/unsubscribe-auth/ASRWY9EuslHGw3JdbVsZ-LYHTZeEqksyks5vec1ygaJpZM4ce7DY.

[t9mike]

For many groups, XML comments are first and foremost consumed by fellow devs on a team -- or the actual developer -- through the source code:

1. By going to definition of an API in the source code
2. Via Intellisense

For (1), having them human readable in source code is critical. And the best way to do that is to have an easier to use syntax.

While we publish APIs internally, because the XML syntax is so burdensome we just don't spend the time to do paras, bullets, real references, etc. in most cases. Since usually it is fellow team dev reviewing definition via (1), this is fine and actually a benefit. Our API users are pretty casual users and can deal with the "big paragraph" summary via Intellisense and are often following samples provided anyway.

If well formatted comments were both easy to enter and easily human readable, pure API users and dev team members would both benefit:

• Devs through easy to read API code comments
• Devs and API users through well formatted Intellisense and stand-alone documentation

I've been coding C# for 14 years. I am stumped that this is still not easier. I'd take improvements in this area over some hot new language feature or Framework enhancement any day.

[CyrusNajmabadi]

I've been coding C# for 14 years. I am stumped that this is still not easier. I'd take improvements in this area over some hot new language feature or Framework enhancement any day.

Everyone feels this way about the things they think would benefit them the most. The difficulty is in realizing that the things that benefit devs the most differs from dev to dev.

[Gaddy]

Hello, do you know if there is any update on this issue?

For my part, it's the end-of-line comments that I desesperately wish to see parsed in intellisense. I know Visual Assist can do it but it's quite a heavy (and costly) plugin to get this one single fix

[Gaddy]

Actually with C++ code, intellisense manages perfectly lightweight comments.

Would there be an easy way to make intellisense manage C# comments the same way than it does for C++ ? Do anyone know if writing such extension would be doable/easy?

[RikkiGibson]

Tangentially related to this: in https://github.com/dotnet/roslyn/issues/44571#issuecomment-659448287 we decided to make /// <param /> tags above a record declaration apply to the primary constructor parameters, and for those elements to flow to synthesized properties in the tooling. I had a somewhat unpleasant experience updating my personal project to use records, because it ended up taking something like:

    /// <summary>
    /// A bus stop in the Corvallis Transit System. This is analogous to the Platform entity in Connexionz.
    /// </summary>
    public class BusStop
    {
        [JsonConstructor]
        public BusStop(
            int id,
            string name,
            double bearing,
            double lat,
            double @long,
            List<string> routeNames)
        {
            Id = id;
            Name = name;
            Bearing = bearing;
            Lat = lat;
            Long = @long;
            RouteNames = routeNames;
        }

        /// <summary>
        /// This stop tag is used to get ETAs for the stop from Connexionz.
        /// </summary>
        [JsonProperty("id")]
        public int Id { get; }

        /// <summary>
        /// The name of the stop, for example: "NW Monroe Ave & NW 7th St".
        /// </summary>
        [JsonProperty("name")]
        public string Name { get; }

        /// <summary>
        /// The angle in degrees between this bus stop and the road. This can be treated as
        /// the angle between the positive X axis and the direction of travel for buses at this stop.
        /// </summary>
        [JsonProperty("bearing")]
        public double Bearing { get; }

        /// <summary>
        /// The latitude value for the stop (between -90 and 90 degrees).
        /// </summary>
        [JsonProperty("lat")]
        public double Lat { get; }

        /// <summary>
        /// The longitude value for the stop (between -180 and 180 degrees).
        /// </summary>
        [JsonProperty("lng")]
        public double Long { get; }

        /// <summary>
        /// List of route names which arrive at this stop.
        /// </summary>
        [JsonProperty("routeNames")]
        public List<string> RouteNames { get; }
    }

and requiring it to change to:

    /// <summary>
    /// A bus stop in the Corvallis Transit System. This is analogous to the Platform entity in Connexionz.
    /// </summary>
    /// <param name="Id">
    /// This stop tag is used to get ETAs for the stop from Connexionz.
    /// </param>
    /// <param name="Name">
    /// The name of the stop, for example: &quot;NW Monroe Ave &amp; NW 7th St&quot;.
    /// </param>
    /// <param name="Bearing">
    /// The angle in degrees between this bus stop and the road. This can be treated as
    /// the angle between the positive X axis and the direction of travel for buses at this stop.
    /// </param>
    /// <param name="Lat">
    /// The latitude value for the stop (between -90 and 90 degrees).
    /// </param>
    /// <param name="Long">
    /// The longitude value for the stop (between -180 and 180 degrees).
    /// </param>
    /// <param name="RouteNames">
    /// List of route names which arrive at this stop.
    /// </param>
    public record BusStop(
        [property: JsonProperty("id")]
        int Id,

        [property: JsonProperty("name")]
        string Name,

        [property: JsonProperty("bearing")]
        double Bearing,

        [property: JsonProperty("lat")]
        double Lat,

        [property: JsonProperty("lng")]
        double Long,

        [property: JsonProperty("routeNames")]
        List<string> RouteNames);

It may not seem like much, but the friction of needing to migrate all the property doc comments to the top of the containing type, and the loss of having "all the stuff about this property" in one place, was somewhat unpleasant. For example, if I decide to F12 to one of these positional parameters, I have to scroll up and scan the comments until I find the doc comment for that parameter.

Basically, I would love to have the option to apply doc comments to parameters directly in syntax in all places that parameters are declared, optionally in a short form that elides the name="..." attribute or the wrapping element entirely.

[bugproof]

1 nice addition would be a shortcut for summary only comment... So instead of

/// <summary>
/// comment
/// </summary>

we could write

/// comment

and it would automatically treat it as <summary>.... like in f# https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/xml-documentation#comments-without-xml-tags

and it shouldn't be a big deal to add it... and instead of 3 lines it would take 1 line and code would instantly become more readable

[adamwalling]

It is telling that visual studio displays xml comments from metadata like this:

        //
        // Summary:
        //     Releases unmanaged and - optionally - managed resources
        //
        // Parameters:
        //   disposing:
        //     true to release both managed and unmanaged resources; false to release only unmanaged
        //     resources.
        public void Dispose();

instead of as it appears in the source

        /// <summary>
        /// Releases unmanaged and - optionally - managed resources
        /// </summary>
        /// <param name="disposing">true to release both managed and unmanaged resources; false to release only unmanaged resources.</param>
        protected virtual void Dispose(bool disposing)

because let's be honest, it's less readable with all the xml baggage. That's why we are using markdown here in github comments and not html tags!

Honestly I'd love the conventions to just be adopted for documentation comments without needing all the xml. Or even just taking the whole thing as a summary.

        /// Releases unmanaged and - optionally - managed resources
        ///     disposing: true to release both managed and unmanaged resources; false to release only unmanaged resources.
        protected virtual void Dispose(bool disposing)

[TahirAhmadov]

I definitely hear the concern of XML comments not being as readable when looking at the code itself. Can this be a request for VS or for other software to allow "collapsing" the doc into a readable format, unless it needs to be modified? 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.

Also, for simple few-word sentences, you can put the <summary> tags on the same line.

[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 https://github.com/dotnet/roslyn/issues/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