This project is read-only.

Documentation summaries without XML tags

Topics: C# Language Design
May 13, 2014 at 11:44 AM
In F#, triple-slash comments are interpreted as summaries by default, if there are no XML tags:
/// Adds 1 to the number
let incr x = x + 1
Java can do the same thing thanks to the way Javadoc comments work:
/** Adds 1 to the number */
public static int increment(int x) { return x + 1; }
However, C# doesn't have that; at best, the summary tags can be put on one line, but it requires more text and distracts from the actual content:
/// <summary> Adds 1 to the number </summary>
public static int Increment(int x) { return x + 1; }
Parsing triple-slash comments without XML as documentation with a summary is very useful to reduce boilerplate syntax since most methods only have a summary, and it's not very complex.
C# 6 seems to be focused on improving small aspects of the language, so I think this is worth investigating.
May 20, 2014 at 5:58 PM
I like it, the xml tags are way to verbose, I also have a habbit to put the tags on a single line, especially for properies.

Not sure if this could cause 'backwards compatibility' issues with existing code that uses /// which now suddenly becomes an uninttended summary comment? The actual code would not break ofcourse.
May 20, 2014 at 7:13 PM
This is something I've wanted forever as well. XML comments are horrific, yet they've persisted in the language for so long unaltered. I'd like to see C# support JavaDoc-like syntax because it is easier to write and read, and it's also more consistent with other languages.