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.

2 thoughts on “Nice doc comment idea”

  1. 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…


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s