[Mono-list] Re: [Mono-docs-list] WebControls Documentation

[Jason Diamond]

>     Personally speaking, I am not in favour of inline-comments. At times,
I
> myself get confused with my comments (if too long). Let there be only and
only
> external documentation, not even of the things like summary, remarks or
param
> options.

This why we have syntax highlighting. After a while, your brain starts to
ignore the text that's green (or whatever color your comments are).

Or, if you have an editor that supports folding, you can completely hide
your comments.

Besides personal taste, there's a some really practical advantages to having
your documentation inline. Since it's parsed by the compiler, it can emit
warnings for types, members, and parameters that aren't documented. It can
automatically convert short references (like String) to fully qualified
references (like System.String). It can warn you when there's a typo in your
references. csc does all of this. mcs will hopefully do the same in the
future.

Jason