[MonoDevelop] Comments on the comment template

[IBBoard]

On 07/07/10 08:47, Levi Bard wrote:
>> It also detects exceptions thrown
> 
> I'm on board just for this.
> 
> However, wasn't the cref= stuff in there for people who generated
> browsable docs from the xmldoc? So in the final version you'd get a
> link you could click and jump to Foo.BarBaz?

I agree - listing exceptions in the documentation is useful. It's one of
the things that I'm torn about between Java and C#. One the one hand it
is useful to know what you might need to catch (as Java forces you to
do), but on the other hand it can lead to lots of wrapped exceptions at
various different levels so that you're not propagating lots of
exception types. C# leaves you with the possibility of not knowing what
might be thrown.

As for the implementation, I think I prefer David's idea. I do think
that the "A <...cref...>" is a bit unnecessary at the moment, but I'm
not sure I'd find the auto-generated text useful as it doesn't tell you
anything that the name doesn't. IMO it's more likely to lead to
documentation that's poor because people went "there's something there,
I'll fix it later" rather than obviously missing documentation (which a
code analyser could detect and warn you about). If you want the cref for
full XML documentation links then I've normally found that you can fit
it in the summary to say "takes an X, does Y with it and returns a Z,
assuming A is true, else destroys the universe as we know it".