This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Mark Kettenis <mark dot kettenis at xs4all dot nl>
- To: stanshebs at earthlink dot net
- Cc: eliz at gnu dot org, dje at google dot com, gdb at sourceware dot org
- Date: Fri, 9 Aug 2013 11:49:23 +0200 (CEST)
- Subject: Re: A new strategy for internals documentation
- References: <5201781A dot 3000607 at earthlink dot net> <83k3jyunt8 dot fsf at gnu dot org> <5202A6D6 dot 8090908 at earthlink dot net> <83li4ct7ot dot fsf at gnu dot org> <CADPb22ToXn8aypnpyHEFrUw_yQQiib=ieCj7WbQLSaZQM00RVg at mail dot gmail dot com> <8361vfu9t4 dot fsf at gnu dot org> <520423A2 dot 6010304 at earthlink dot net>
> Date: Thu, 08 Aug 2013 16:02:58 -0700
> From: Stan Shebs <stanshebs@earthlink.net>
>
> 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.