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.