35
Vote

Light syntax for XML documentation

description

class Ticket
{
  /// <summary>
  /// Ticket title (short name)
  /// </summary>
  public string Title { get; set; }

  /// <summary>
  /// Ticket full description
  /// </summary>
  public int Age { get; set; }
}
Introduce shorter way to write <summary>-only XML documentation, just like in F#:
class Ticket
{
  /// Ticket title (short name)
  public string Title { get; set; }

  /// Ticket full description
  public int Age { get; set; }
}

comments

daviddesloovere wrote Jun 17, 2014 at 12:41 PM

Tools like Sandcastle will also have to be update then.

ControlFlow wrote Jun 17, 2014 at 12:50 PM

Sandcastle should work with *.xml documentation files generated by compiler, isn't it? Those files should looks the same, since C# can treat such proposed comments as a content of a single <summary> tag.

daviddesloovere wrote Jun 17, 2014 at 1:42 PM

You are 100% correct. How did I miss that...
Let's drop those <summary> tags then!

MgSam wrote Jun 18, 2014 at 4:48 PM

Only improving the "summary" portion seems rather limiting. I'd prefer fixing the whole broken syntax.

I had already made a feature request for the idea of improving XML docs: https://roslyn.codeplex.com/workitem/188 (note that my suggested syntax is just one possible solution).