This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Yao Qi <yao at codesourcery dot com>
- To: Doug Evans <dje at google dot com>
- Cc: Eli Zaretskii <eliz at gnu dot org>, Stan Shebs <stanshebs at earthlink dot net>, gdb <gdb at sourceware dot org>
- Date: Sat, 10 Aug 2013 09:12:07 +0800
- 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> <CADPb22QNbWQhPGQ2Utfh=C+hFH5iJMrR30G=BE646Z87R_1Yfg at mail dot gmail dot com>
On 08/09/2013 07:04 AM, Doug Evans wrote:
I'm one that thinks that there is not enough, and that expanding the
comments is not enough. For one there's a higher level / descriptive
view that's missing with that approach. Plus the S/N ratio when faced
with reading all the source code is much lower than when able to
browse something generated from the comments in the code.
Code comments can be about high-level view too. Existing comments in
the beginning of event-loop.h and remote-notif.c are about high-level
view.
Document is generated from the comments, and we need some special
annotations or markups to identify these comments are descriptive views
for a certain module or components. Doxygen or other documentation
generators are able to do that.
--
Yao (éå)