Re: A new strategy for internals documentation
Mark Kettenis <[email protected]>
| Newsgroups | gmane.comp.gdb.devel |
|---|---|
| Message-ID | <[email protected]> |
> Date: Thu, 08 Aug 2013 16:02:58 -0700 > From: Stan Shebs <[email protected]> > > 3. Introduce an annotation/structured scheme in source code comments. > > You're skeptical, but not opposed to this, right? It's not going to make the source code comments more readable. Will probably make people focus on getting the sybtax of the annotations right instead of the actual context. > 4. Use Doxygen. > > Are you for or against, or indifferent? > > (For me Doxygen gets the nod by elimination, if nothing else. In the > rather lengthy > > http://en.wikipedia.org/wiki/Comparison_of_documentation_generators > > there are not a lot of options that are portable, GPL, etc. LLVM's use > of Doxygen, http://llvm.org/doxygen/index.html , seems pretty useful.) Yeah, that's a typical example of doxygen-generated documentation. Lots of function prototypes, a few inheritance diagrams, and barely any actual content. Not my defenition of useful. In fact I'm pretty much conditioned such that my response to seeing doxygen generated pages is to not ever bother reading it. Stan, I fear you're proposing a technical solution for a social probleem.