Re: The Documentation!

[Matt Rice]

--- Stefan Bidigaray <stefanbidi@gmail.com> wrote:

> As some of you may know, I've been slowly writing
> documentation for the GUI
> library, and I've become amazed at the utter chaos
> of the documentation.
> Not as in things are wrong, but as they are written.
>  Two things that seem
> to sometimes slow me down (not a lot) is the fact
> that sometimes the
> documentation is written in the .m files and some
> times in the .h files.

I think this would be great, 

and recall a thread in the past where this had been
discussed, (the paragraph beginning with FWIW)

http://lists.gnu.org/archive/html/gnustep-dev/2004-07/msg00045.html

in the thread there was some discussion of of
disabling 
building docs from sources and only generating them
from headers.

I suppose that is still waiting on someone to migrate
all the stuff in sources to headers.

> Another thing, which is more of a pet peeve of mine
> is the fact that some
> writting are done with * at the beginning of the
> line, which greatly helps
> when trying to skip over stuff that is already
> documentation and some don't,
> like this:
> 
> /** Blah blah blah
>  *   blah blah blah
>  */

Well, some editors add the * at the beginning
automatically, I don't think there'd be any problem
with you adding them.

though those same editors generally create
/*
 * style comments
 */

if you're trying to easily differentiate the /*
comments from /** ones

but for people who use editors that don't
automatically add it, it might be tedious if this were
anointed
'the standard autogsdoc comment format'
similarly for editors that add them it'd be tedious to
remove
them from /* */ style comments..

I don't know what editor you use, but maybe it'd be
possible to add some custom text color to /** */ style
coments? (assuming you are not color blind)

so yeah, i'm a little weary of this last thing, but if
it helps you to contribute docs, i'd say have at it


 
____________________________________________________________________________________
Finding fabulous fares is fun.  
Let Yahoo! FareChase search your favorite travel sites to find flight and hotel 
bargains.
http://farechase.yahoo.com/promo-generic-14795097