Nice doc comment idea

I've just been reading the transcript of a whiteboard session with Anders Hejlsberg and one of the questions is really, really good:

Question: My problem is I’ve got these XML doc comments that are duplicated. I just strip off one. I guess it would be a neat language feature to be able to somehow indicate this is my primary- my big method, right? With all the parameters. Then the other ones are just going to borrow that XML doc comment.

Hejlsberg: Yes, okay. Now that I think is- that’s not a bad idea. That yes, they should be able to share the documentation. I can sympathize with that.

That's not just "not a bad idea". That's a fantastic idea. When I was writing the BitConverter and BinaryReader etc equivalents in my miscellaneous utility library the doc comments for the overloads took significantly longer to write than the actual code. (Most of the code was just each overload calling a "master" routine.) Now, sometimes that comment won't be exactly the same for each overload; sometimes there'll effectively be placeholders: "Converts the specified ${type} value into ${n} bytes" or whatever. I don't know exactly how this could be done elegantly (and I'm not actually suggesting the ${token} syntax!), but it's something that should be strongly considered for a later version of C#. It could make life a lot simpler in some cases.

Published Tue, Jan 10 2006 8:46 by skeet

Comments

# re: Nice doc comment idea

The next NDoc release will have a similar feature -- a "documentation inheritance" tag that duplicates the specified comment block for the class member on which it appears. If no source comment is specified, NDoc will automatically use the corresponding base class member, interface member, or overloaded sibling with an "overloads" tag.

The big drawback: since NDoc only creates formatted help files, none of the inherited documentation shows up in Intellisense. For that reason alone, I'm not planning to use this feature.

I'd definitely appreciate a Microsoft solution that integrates with Intellisense...

Wednesday, January 11, 2006 3:03 AM by Chris Nahr

# re: Nice doc comment idea

I was also wondering why you needed to copy big parts of the xml comments to the comment block of each overloaded operation.

Having the possibility to share the documentation is indeed a very great idea!

Wednesday, January 11, 2006 12:17 PM by Gabriel Lozano-Morán