RE: [pooma-dev] [PATCH] Reference documentation structure

[Richard Guenther]

On Sun, 9 Feb 2003, James Crotinger wrote:

> Hi Richard,
>
> Is this structure a rearrangement of the source? I do not think this would
> be a good idea since CVS doesn't support moving files, and losing the
> history is bad.

No, its not a rearrangement of the source. But just structuring the source
which in a doxygen way is specifying "groups" in which I can later put
files. I originally had this group files in the src/ directory, but as
they contain introductional documentation to a (sometimes) large part of
the code I thought placing them beyond the docs/reference directory is a
better idea.

Just to give you an idea the plan is to add per-source-file overview
together with placing in a group in every source file, f.i. for
FieldCentering.h this would look like

/** @file
 * @ingroup Field
 * @brief
 * specifies value locations within a field's cell
 *
 * Centering
 *   - specifies value locations within a field's cell
 * CanonicalCentering
 *   - yields some canonical centerings
 * canonicalCentering<Dim>(type, discontinuous, dimension)
 *   - yields the specified canonical centering
 */


I'm open to suggestions regarding the structure itself, as I'm not really
satisfied with it. Also better suggestions for placing group related
documentation is welcome (though I'm satisfied with placing this beyond
docs/reference - just maybe not in so much files?).

Richard.