Re: GNUstep Coding Standard Additions

[Nicola Pero]

> >>Where should gsdoc comments go?  Mostly, it is in the implementation 
> >>files.
> > 
> > There are different opinions on this matter ... ;-)
> > 
> > Some people don't use autogsdoc and they just read headers. :-)
> > 
> [snip]
>
> Hmm.. to paraphrase, you prefer headers over other systems because:
> 
> (a) the customised documentation system isn't immediately apparent
> 
> or
> 
> (b) the docs aren't immediately locatable
> 
> is that right?

Headers are good because they are

 1. standard across multiple projects (including non-GNUstep projects 
obviously)

 2. standard to browse with any editor/ide that supports basic C

 3. standard to browse without any editor/ide by just using 'cat' / 'less'
and 'grep'

 4. always available, you don't need a documentation system


If you combine 1. and 2. it means you can browse eg libc headers and
GNUstep headers from the same tools in the same way jumping from one to
the other without even feeling the difference.  That's good. :-)

... but nicely formatted documentation in html on the web is also
extremely good.  But different users use the stuff in different way.  
Serving multiple users and usage patterns is generally good. :-D


> So, if you have nice docs which were easily located it would be a 
> non-issue for you?

I don't see your point.  If you have documentation in headers, you can
both have nicely formatted html docs for the browsing programmer, and the
doc in the headers for hardcode C/unix programmers.

If you have documentation in the source code, you can only have the html
version.


Also, the real point is that documentation for the public API should be in
the public headers where the public API is declared, not in the private
implementation files.

If you have the documentation in the headers -- where all and only the
public symbols are declared --, you can more easily make sure that every
public symbol is documented.

Btw if you look at the header and you have visibility only of the public
symbols and API, and that helps you to document the stuff as publicly
visible, without getting confused or distracted by the implementation
details.

Anyway that's just my opinion.

Thanks