> >>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 _______________________________________________ Discuss-gnustep mailing list [email protected] http://lists.gnu.org/mailman/listinfo/discuss-gnustep
