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

Dan Lewis dihlewis@yahoo.co.uk
Fri, 8 Mar 2002 10:07:21 +0000 (GMT)

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


Do You Yahoo!?
Everything you'll ever need on one web page
from News and Sport to Email and Music Charts