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

[Dan Lewis]

 --- Jason Diamond <jason@injektilo.org> wrote: 
> 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).

Microsoft's comments include cookbook examples -- literally screenfuls of
comments. It would be really nice to include this level of detail for some
classes. But I don't feel this would be maintainable code without the kind of
advanced editing support you're talking about.

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

A good documentation tool should do this for you, making sure your
documentation files are 100% consistent with assemblies they describe. My
personal feeling is that the compiler should compile code, not documentation.
Unfortunately csc insists on doing two jobs.

Dan.


__________________________________________________
Do You Yahoo!?
Everything you'll ever need on one web page
from News and Sport to Email and Music Charts
http://uk.my.yahoo.com