/*! \mainpage
Sources
The src directory contains all source code for all modules
and applications in the tree. This directory contains the following
subdirectories:
- Directory config:
- Contains files related to the build system. This contains no actual
product source code. Rather, it contains things like
Makefiles and scripts.
- Directory af (\ref af_overview):
- Contains source code for application-neutral cross-platform framework.
- Directory hello:
- Contains source code for the "Hello World" sample application.
- Directory other:
- Contains source code for forked third-party libraries.
For example, we use a librarified subset of ispell, which is
stored here. In general, put libraries in 'other' if we are making
substantial modifications to the code. DO NOT DO THIS LIGHTLY!!
- Whenever possible, it's better to use existing libraries as peer
modules of the abi tree. Minor bug fixes there are fine (please
send the fix back to the original author). Customizations to make
the library fit into our build system are fine.
- Source code in 'other' is not required to comply with every one of our
coding guidelines. Don't make gratuitous sweeping changes just to fix
the indent level on someone else's library.
- Directory text (\ref text_overview):
- Contains source code for the text-editing library used by
various applications.
- Directory wp (\ref wp_overview):
- Contains source code for the word processor application.
Subdirectories below may have additional hierarchy to further break
things down by module. However, eventually, source code should find
itself in a directory which indicates the portability of the code
within it. For example, cross-platform code should always be placed
in a subdirectory called 'xp'. Win32-specific code should be in a
subdirectory called 'win'.
Issues / TODO
This is a list of issues and/or problems that need to be addressed in
the code. Some of these are probably also registered in the bug
database described by their various symptoms.
This however, is an attempt to keep track of things that should be
cleaned up / rewritten, even if it's not clear if there are actual
bugs caused by the existing implementation.
When adding / removing entries, be sure to go through the bug database
to add references to bugs representing symptoms or remove bugs fixed
by changes. When adding a new entry, please put your name after it,
optionally linking to a descriptive posting on the mailing list.
Text
- Importers rely on superfluous use of fl_BlockLayout::format() to
work around (assumed) problems in
fl_BlockLayout::_stuffAllRunsOnALine() and the line breaker code. (Martin
Sevior)
- Existing code should be changed to provide view (non-mutating)
and controller (mutating) accessors to the PieceTable. (Sam
TH)
Build System
- We should eventually move to an auto(conf, make) style build
system, at least on platforms that support it. This will make it
possible to use features of the OS that we are currently unable to.
AbiWord Doxygen Documentation
Doxygen is the tool used to
extract documentation from the sources and present it in the present
form.
The AbiWord sources are not fully doxygenized yet - please feel free
to add documentation to functions/variables you happen to hack
on. See below for details.
Generating The HTML Documentation
To regenerate documentation, run make dox from the top level
(abi) directory. This rule invokes the doxygen tool.
You can get Doxygen for many platforms at the Doxygen homepage www.doxygen.org. The tool also
ships with Red Hat Linux and Debian.
If you want to use the documentation off-line for reference,
generating it locally is a good idea - it may become possible to
download it all in an archive eventually - but by generating it
locally, you can easily update it when you add comments yourself.
The HTML documentation on the AbiSource home page gets regenerated
hourly from the HEAD of the CVS repository.
AbiWord Doxygen Structure
The Doxygen configuration is kept in
abi/src/.doxygen.cfg. The INPUT variable contains
the list of directories to be scanned when generating documentation.
At present time only the text directory (the AbiWord backend) is
actually scanned - but it's simple to add other directories.
Each component of AbiWord has an overview description stored in a
%README.TXT file. This is where you want to put the grand
overview - and please add text if you gain insight on stuff not
presently documented in the %README.TXT files.
From the %README.TXT files you can refer to class/function
names and the outcome is nice guided tour where people can read the
overview description and dive into the code from there. It is of
course also possible to just go directly to the various hierarchies
and lists at the top of all pages.
AbiWord Doxygen Style Guide
Just a few guidelines for now. See fp_Container which adheres to these
(I think) and is comment complete.
Please try to adhere to these as it makes for more consistent
documentation (looks as well as content) - which gives a more
professional feel to it. If you have ideas for other guidelines,
please post them to the developer list and we'll discuss it.
- KISS! We don't want the source code to drown in fancy formatted
comments.
- Comments should be kept in raw ASCII where possible. If you feel
structure or typeface commands would help, use the HTML tags
which most people understand.
- The first line of a comment block is the brief description (do not
use \\brief). Follow it by input/output descriptions, then a
longer comment if necessary. Finally add \\note, \\bug, \\see,
\\fixme as necessary.
- Put the descriptions by the function definition, not the
declaration. Always use the
\verbatim
/*!
Short description
\param param1 Param 1 Description
long descriptions should be indented like this
\retval paramN+1 Return value ParamN+1 description
\return Return value description
Long description
...
\note Note ...
\fixme FIXME description 1
\bug Bug description 1
\see otherClass::otherFunction1
*/
\endverbatim
variant of the comment marker, and leave the opening and closing
markers on empty lines.
- In the brief line, describe what the function
does, not how it does it. Leave the input/output details
to the appropriate lines (accessors excepted). See
fp_Container::isEmpty.
- Always add input/output details for a function: \\param,
\\retval (return value via pointer parameter), \\return (actual
function return value).
A list of quick hints about doxygen syntax. Please see www.doxygen.org for the full syntax.
- Suppress links with \% (doxygen will add links to any function
or filename).
- Note that "-" characters can be used for simple bullet list
creation. I wonder if we should suppress that in favor of HTML
tags.
- Sometimes you want to write a class name or similar in plural,
but doxygen will not add a link. You can work around that by
something like "\\link fp_Run fp_Runs \\endlink" but it's horrible
to look at in the raw text. So do without it, rephrase, put the
singular word in parenthesis "fp_Runs (fp_Run)", or assume the
reader can find the class in the class list.
- Add references to named sections of the documentation with \\ref
(e.g. \ref fmt_overview which links to the %README.TXT
in the text/fmt directory on account of it having a
\\page command).
We may also want to discuss allowing simple figures for documenting
hairy code. I think it should be possible - but it should not be done
on account of comment text: the programmer should not be required to
look at the doxygen output to understand the code!
Do we want the brief descriptions and return/param text to be in a
certain language style? Would help make the doc look consistent, but
may be too much detail for people to bother with complying. Please see
fp_Container for a suggested style (i.e., compute vs. computes).
*/