Roslyn: Proposal: nameof in C# comments

[copernicus365]

It would be nice if the nameof keyword could be used in XML comments. Renaming the type in code would then update the type names in the comments (like paramrefs already do).

Perhaps this could be made available by prepending the @ symbol before nameof:

/// <summary>
/// Lorem ipsum @nameof(Foo) likes @nameof(Bar).
/// </summary>
public class Foo { }
public class Bar { }

XML comment consumers (like VisualStudio) could leave these just as they are, though it's possible some consumers could, when pretty displaying the comments (for display purposes only, like in a popup), treat @nameof(Bar) like it is <c>Bar</c>.

If this were feasible, maybe it would be worth considering even allowing constants in comments as well. That would be one terrific way of getting around the annoying problem of when it would be nice to share a comment or part of a comment in multiple overloads, etc. Maybe for simplicity's sake (simple because the keyword makes things straightforward) this could be done by using the @nameof(Foo.Pi) keyword there too. But let's keep this constants business separate for now.

FYI, Recommended Tags for Documentation Comments (C# Programming Guide)

[svick]

How is @nameof(Foo) different from <see cref="Foo" />?

[copernicus365]

Shucks, I forgot about this attribute. It doesn't help that 'see' (which comes up in intellisense) is not so clear what it refers to. But the fact that there is a native XML way of doing this will move the bar high before a non-XML way were used like this. So I should probably close this, thanks for the info sir. The benefit now would simply be that this is a non-XML way which looks a lot cleaner, and requires only a single keyword, not an XML <elemName attribute="" />. Personally I don't like these wordy XML ways of referencing code types, most the time we're reading these comments in the raw code, and all that XML marking makes things cluttered to read. But at least this one has a short element and attribute name.

[svick]

Personally I don't like these wordy XML ways of referencing code types, most the time we're reading these comments in the raw code, and all that XML marking makes things cluttered to read.

I agree, but I think the solution would be to add a completely new non-XML syntax, instead of just improving one aspect of it. And that has already been proposed: #85.

[copernicus365]

Great point, and thanks for the link to that other issue. That expresses my sentiments well:

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.

Unlike that author I am not anti-XML, but in this case, for primarily human-readable documentation, it is a poor solution in my view. And how interesting it is that proposed solution uses the '@' symbol copiously as well. (I am influenced by Razor).