Subject: A question of comment mangling...
From: Jesper Skov (jskov@redhat.com)
Date: Thu Dec 28 2000 - 04:02:28 CST
Some of you probably know I've decided to add/enhance backend
documentation, using doxygen as a means to extract the documentation
from the sources.
Before I get carried away, I'd like to ask people to consider how much
effort should be put into making the generated documentation look
nice. It's basically a choice between:
o Pretty nice HTML/PDF/printed docs on behalf of (slightly?) mangled
code comments.
o Simplistic (and IMO ugly) HTML/PDF/printed docs, keeping code
comments in pure form.
I think the former would be advantageous for a few reasons:
o The doxygen syntax is not hard to understand, and it's only really
needed in a few places to get a nice looking output.
o Regenerating the documentation is a snap and will become a makefile
rule. So everybody can regenerate local (off-line browsable) pretty
documentation from the sources. Binaries of oxygen are available
for Windows and Linux (and probably builds without problems on at
least other UNIXes, QNX and BeOS).
o [this is the important one] The need for use of explicit formatting
commands should be limited to overview descriptions. The majority
of the comments would probably not benefit from formatting info.
o Having nicely formatted overviews promotes (I hope) people's
interest in using the resulting documentation.
As an example, I here include two versions of the fl_DocLayout.h
overview comment and below are attached the two resulting HTML
files. To be fair, the simple HTML version could get a bit prettier by
making a few changes to the layout of the comment text (without using
doxygen formatting commands).
=============================================================== simple
/*! \mainpage
FL_DocLayout is a formatted representation of a specific
PD_Document, formatted for a specific GR_Graphics context.
A FL_DocLayout encapsulates two related hierarchies of objects.
The "logical" hierarchy corresponds to the logical structure
of the document, and consists of a list of fl_SectionLayout
objects, which are in turn composed of fl_BlockLayout objects.
The "physical" hierarchy, by contrast, encapsulates the
subdivision of physical space into objects of successively
finer granularity. Thus, a FL_DocLayout is also a list of
Pages, each of which was constructed during the process of
formatting the document. In turn,
o each fp_Page is a list of fp_Columns
o Each fp_Column is a list of fp_Lines
o Each fp_Line is a list of Runs.
Finally, each fp_Run contains some fragment of content from
the original document, usually text.
*/
======================================================================
================================================================ fancy
/*! \mainpage
FL_DocLayout is a formatted representation of a specific
PD_Document, formatted for a specific GR_Graphics context.
A FL_DocLayout encapsulates two related hierarchies of objects.
The \e logical (or \e content) hierarchy corresponds to the
logical structure of the document.
- each FL_DocLayout contains a list of fl_SectionLayout objects
- each fl_SectionLayout are composed of fl_BlockLayout objects
Where each fl_BlockLayout corresponds to a logical element in the
PD_Document (i.e., usually a paragraph of text).
The \e physical (or \e layout) hierarchy, by contrast,
encapsulates the subdivision of physical space into objects of
successively finer granularity.
- each FL_DocLayout contains a list of fp_Page objects, each
of which was constructed during the process of formatting
the document
- each fp_Page is a list of \link fp_Column fp_Columns \endlink
- each fp_Column is a list of \link fp_Line fp_Lines \endlink
- each fp_Line is a list of \link fp_Run fp_Runs \endlink
Finally, each fp_Run contains some fragment of content from the
original document, usually text.
*/
======================================================================
I hope to get some feedback, good or bad :)
Btw, the complete documentation output from the abi/src/text is 8MB
(that is, 8MB of autogenerated documentation - I have added no
documentation at this time). I wish I could upload it somewhere - or
maybe I should look at getting apache running here (I have an ADSL
connection).
Jesper
FL_DocLayout is a formatted representation of a specific PD_Document, formatted for a specific GR_Graphics context.
A FL_DocLayout encapsulates two related hierarchies of objects.
The logical (or content) hierarchy corresponds to the logical structure of the document.
The physical (or layout) hierarchy, by contrast, encapsulates the subdivision of physical space into objects of successively finer granularity.
1.2.4 written by Dimitri van Heesch,
© 1997-2000
FL_DocLayout is a formatted representation of a specific PD_Document, formatted for a specific GR_Graphics context.
A FL_DocLayout encapsulates two related hierarchies of objects.
The "logical" hierarchy corresponds to the logical structure of the document, and consists of a list of fl_SectionLayout objects, which are in turn composed of fl_BlockLayout objects.
The "physical" hierarchy, by contrast, encapsulates the subdivision of physical space into objects of successively finer granularity. Thus, a FL_DocLayout is also a list of Pages, each of which was constructed during the process of formatting the document. In turn,
each fp_Page is a list of fp_Columns Each fp_Column is a list of fp_Lines Each fp_Line is a list of Runs.
Finally, each fp_Run contains some fragment of content from the original document, usually text.
1.2.4 written by Dimitri van Heesch,
© 1997-2000
This archive was generated by hypermail 2b25 : Thu Dec 28 2000 - 04:02:46 CST