[PATCH] Reference documentation

[Richard Guenther]

Hi!

I'd like to continue to build up reference documentation creation
infrastructure. This second step adds grouping following the pooma
source directory structure to the generated doxygen pages. Also some of
the head pages of the groups will feature an introduction like overview.

Tested by making the reference documentation using doxygen 1.3.2 and
spellchecking the group descriptions using ispell.

Thanks,
Richard.


2003Oct05  Richard Guenther <address@hidden>

        * docs/reference/Makefile: fix clean rule.
        docs/reference/array.doxygen: new file.
        docs/reference/field.doxygen: new file.
        docs/reference/particles.doxygen: new file.
        docs/reference/tulip.doxygen: new file.
        docs/reference/connect.doxygen: new file.
        docs/reference/internal.doxygen: new file.
        docs/reference/partition.doxygen: new file.
        docs/reference/unused.doxygen: new file.
        docs/reference/databrowser.doxygen: new file.
        docs/reference/io.doxygen: new file.
        docs/reference/pete.doxygen: new file.
        docs/reference/utility.doxygen: new file.
        docs/reference/domain.doxygen: new file.
        docs/reference/layout.doxygen: new file.
        docs/reference/pooma.doxygen: new file.
        docs/reference/engine.doxygen: new file.
        docs/reference/main.doxygen: new file.
        docs/reference/threads.doxygen: new file.
        docs/reference/evaluator.doxygen: new file.
        docs/reference/objects.doxygen: new file.
        docs/reference/tiny.doxygen: new file.

Index: Makefile
===================================================================
RCS file: /home/pooma/Repository/r2/docs/reference/Makefile,v
retrieving revision 1.1
diff -u -u -r1.1 Makefile
--- Makefile    6 Feb 2003 22:14:11 -0000       1.1
+++ Makefile    5 Oct 2003 14:32:33 -0000
@@ -1,13 +1,13 @@
-.PHONY: reference clean default
+.PHONY: html clean default

 default:
        @echo "Valid targets are:"
        @echo " html      - generate reference manual from source using doxygen"
        @echo " clean     - remove files generated from doxygen"

-html:
+html: clean
        doxygen doxygen.conf

 clean:
-       rm -Rf reference
+       rm -Rf html

--- reference/array.doxygen     1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/array.doxygen 2003-02-09 
00:03:24.000000000 +0100
@@ -0,0 +1,5 @@
+/**
+ * @defgroup Array Arrays
+ * @ingroup Objects
+ *
+ */
diff -urN reference/connect.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/connect.doxygen
--- reference/connect.doxygen   1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/connect.doxygen       
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,32 @@
+/**
+ * @defgroup Connect
+ * @ingroup Utilities
+ * Classes/Files for managing connections to external agents such as
+ * visualization tools.
+ *
+ * Support for using the PAWS library is available. PAWS provides a
+ * mechanism for sharing multidimensional array and simple scalar
+ * variables between separate parallel programs.
+ *
+ * Support for using the Lux library for run-time visualization is
+ * available.
+ *
+ */
+
+/**
+ * @defgroup Lux
+ * @ingroup Connect
+ *
+ * Support for using the Lux library for run-time visualization.
+ *
+ */
+
+/**
+ * @defgroup Paws
+ * @ingroup Connect
+ *
+ * Support for using the PAWS library. PAWS provides a
+ * mechanism for sharing multidimensional array and simple scalar
+ * variables between separate parallel programs.
+ *
+ */
diff -urN reference/databrowser.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/databrowser.doxygen
--- reference/databrowser.doxygen       1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/databrowser.doxygen   
2003-02-09 00:03:32.000000000 +0100
@@ -0,0 +1,5 @@
+/**
+ * @defgroup DataBrowser
+ * @ingroup Utilities
+ *
+ */
diff -urN reference/domain.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/domain.doxygen
--- reference/domain.doxygen    1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/domain.doxygen        
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,41 @@
+/**
+ * @defgroup Domain Domain Objects and Modifiers
+ * @ingroup Structuring
+ * These are classes which handle specifying a domain and modifying it.
+ *
+ * The types of domains can be divided into two classes, namely integer
+ * domains and continuous domains.
+ *
+ * Integer domains include
+ * - int
+ * - Loc<Dim>
+ * - Interval<Dim>
+ * - Range<Dim>
+ * - Grid<Dim>
+ *
+ * The only continuous domain class is Region<Dim>. There are a few special
+ * domain classes, namely NullDomain, AllDomain and ErrorDomain.
+ *
+ * All domain classes come with their corresponding traits class
+ * DomainTraits<class> which is used to manage operations on domains
+ * such as
+ * - splitting domains with the split function
+ * - querying if domains overlap using the touches function
+ * - querying the intersection of two domains using the intersect function
+ * - growing/shrinking Interval<Dim> using the shrinkRight, growRight,
+ *   shrinkLeft and growLeft functions
+ * - finding the equivalent subset for a domain from a given transformation
+ *   using the equivSubset function
+ * - remove the overlap between two Interval<Dim> and return a vector of the
+ *   resulting domain using the DomainRemoveOverlap function
+ * - querying if one domain contains another using the contains function
+ *
+ * Domains can be modified by arithmetic operations and new domains can
+ * be constructed using the helper classes in NewDomain.h and the LeftDomain
+ * and RightDomain wildcard classes.
+ *
+ * You can iterate through domains by FIXME.
+ *
+ * Some domains can be sliced FIXME.
+ *
+ */
diff -urN reference/engine.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/engine.doxygen
--- reference/engine.doxygen    1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/engine.doxygen        
2003-10-05 16:33:03.000000000 +0200
@@ -0,0 +1,52 @@
+/**
+ * @defgroup Engine Engines
+ * @ingroup Objects
+ *
+ * Engine related classes/files.
+ *
+ * Engines provide the storage for Arrays and Fields and handle
+ * domain decomposition, taking sub-views and accessing components
+ * transparently by providing a common interface to their users.
+ *
+ * Engine are usually defined recursively. Engines categorize into
+ * engines allocating storage for data, engines that provide access
+ * to computed data and engines providing modified access to other
+ * engines.
+ *
+ * For the first category, the storage engines, the following are
+ * available:
+ *  - Engine < Dim, T, Brick >
+ *  - Engine < Dim, T, CompressibleBrick >
+ *  - Engine < Dim, T, Dynamic >
+ *  - Engine < Dim, T, ConstantFunction >
+ *
+ * For the second category, the computation engines, the following
+ * are available:
+ *  - Engine < Dim, T, IndexFunction < Functor > >
+ *  - Engine < Dim, T, StencilEngine < Function, Expression > >
+ *  - Engine < Dim, T, UserFunctionEngine < UserFunction, Expression > >
+ *  - Engine < Dim, T, ExpressionTag < Expr > >
+ *
+ * For the second category the most important engine types include:
+ *  - Engine < Dim, T, Remote < Tag > >
+ *  - Engine < Dim, T, MultiPatch < LayoutTag, PatchTag > >
+ *  - Engine < Dim, T, CompFwd < Eng, N > >
+ *  - Engine < Dim, T, IndirectionTag < A1, A2 > >
+ *  - Engines of the category
+ *    Engine < Dim, T, ViewEngineType >, where
+ *    ViewEngineType is one of
+ *    BrickView,
+ *    MultiPatchView<LayoutTag, PatchTag, Dim>,
+ *    DynamicView
+ *    and ViewEngine<OriginalDim, ViewedEngineTag>
+ *
+ * Views of Engines can be constructed by using the NewEngine<> traits
+ * class which takes the to be viewed engine type and the subsetting
+ * domain type as template parameters. NewEngine<> then defines the type
+ * of the ViewEngine as Type_t typedef member.
+ *
+ * FIXME: Introduce NewEngineEngine<>, NewEngineDomain<> and
+ * newEngineEngine() and newEngineDomain() with their concepts.
+ */
+
+
diff -urN reference/evaluator.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/evaluator.doxygen
--- reference/evaluator.doxygen 1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/evaluator.doxygen     
2003-10-05 16:33:49.000000000 +0200
@@ -0,0 +1,29 @@
+/**
+ * @defgroup Evaluator
+ * @ingroup Objects
+ *
+ * The evaluators present different ways to operate on Arrays and Fields.
+ *
+ * This includes Fortran-like manual looping over the patches of the
+ * data using the PatchFunction<> mechanism which supports multiple
+ * input data but only one output. (PatchFunction.h, PatchKernel.h)
+ *
+ * Another way to operate is using the ScalarCode<> facility which
+ * presents something like a n-argument stencil operation with some
+ * of the arguments being the output. (ScalarCode.h, ScalarCodeInfo.h,
+ * MultiArgKernel.h, MultiArgEvaluator.h)
+ *
+ * Evaluating a functor at a whole domain is done using the LoopApplyEvaluator.
+ * (LoopApply.h)
+ *
+ * The most simple way is to use POOMA expressions who are evaluated
+ * via ExpressioKernel objects. (ExpressionKernel.h)
+ *
+ * The internal evaluator objects are templated on the patch type which
+ * gets constructed from the expression node types using the
+ * EvaluatorCombine<> traits class and produce the tags
+ * RemoteMultiPatchEvaluatorTag, MultiPatchEvaluatorTag, 
RemoteSinglePatchEvaluatorTag
+ * and SinglePatchEvaluatorTag. The MainEvaluatorTag specialized class is
+ * the root of any evaluation.
+ *
+ */
diff -urN reference/field.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/field.doxygen
--- reference/field.doxygen     1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/field.doxygen 2003-02-09 
00:06:50.000000000 +0100
@@ -0,0 +1,54 @@
+/**
+ * @defgroup Field Fields
+ * @ingroup Objects
+ *
+ * Field related classes/files. Important classes include Field, FieldEngine
+ * Centering and CanonicalCentering.
+ *
+ */
+
+/**
+ * @defgroup Mesh Field Meshes
+ * @ingroup Field
+ *
+ * Meshes provide a way to attach coordinate information to the
+ * vertices of a grid. You can choose between different mesh types
+ * which constrain positions in a different way. All available meshes
+ * are rectilinear, i.e. are constructed as outer product of spacing
+ * vectors.
+ *
+ * To query a mesh for its positions or similar properties use the
+ * functions positions(), outwardNormals(), coordinateNormals(), cellVolumes(),
+ * faceAreas() and edgeLengths().
+ *
+ * Predefined mesh types are:
+ *  - UniformRectilinearMesh which defines a uniformly spaced rectilinear mesh,
+ *  - RectilinearMesh which defines a arbitrarily spaced rectilinear mesh,
+ *  - NoMesh which defines a mesh without a mesh.
+ *
+ * Meshes are completed by one of Cartesian, Cylindrical or Spherical
+ * coordinate system classes. Complete types for mesh can be constructed
+ * using the MeshTraits traits class and the appropriate tag classes for
+ * the mesh type and the coordinate system type.
+ *
+ */
+
+/**
+ * @defgroup DiffOps
+ * @ingroup Field
+ *
+ */
+
+/**
+ * @defgroup Relations Field Relations
+ * @ingroup Field
+ *
+ * Relations are FIXME.
+ *
+ * Usable predefined relations include boundary conditions of which
+ * the following are available:
+ *  - ConstantFaceBC
+ *  - PeriodicFaceBC
+ *  - PosReflectFaceBC
+ *
+ */
diff -urN reference/internal.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/internal.doxygen
--- reference/internal.doxygen  1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/internal.doxygen      
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,7 @@
+/**
+ * @defgroup Internal Internal classes/files
+ *
+ * Not of interest to the pooma user, but maybe
+ * to the pooma developer.
+ *
+ */
diff -urN reference/io.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/io.doxygen
--- reference/io.doxygen        1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/io.doxygen    2003-02-06 
22:30:56.000000000 +0100
@@ -0,0 +1,11 @@
+/**
+ * @defgroup IO
+ * @ingroup Utilities
+ *
+ * IO related classes/files.
+ *
+ * IO is currently supported to the DiscField format as
+ * designed for %Pooma r1 by Bill Humphrey only. FileSetReader
+ * and FileSetWriter are the classes you are looking for.
+ *
+ */
diff -urN reference/layout.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/layout.doxygen
--- reference/layout.doxygen    1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/layout.doxygen        
2003-10-05 16:35:33.000000000 +0200
@@ -0,0 +1,39 @@
+/**
+ * @defgroup Layout Layouts - Laying out Domains
+ * @ingroup Structuring
+ *
+ * A layout combines domain information and guard cell (both internal
+ * and external) information and maps the domain to a specified partition.
+ * So related topics are the \ref Domain and \ref Partition groups.
+ *
+ * All layouts operate with domains based on Interval<Dim>, i.e. a
+ * continuous integer domain. This domain gets distributed/tiled in a
+ * different way for different layout classes, namely
+ * - DomainLayout does not tile/distribute the domain, hence it is applicable
+ *   for local computation only
+ * - GridLayout tiles/distributes the Dim-dimensional domain by constructing
+ *   a (possibly) non-uniform rectilinear grid of subdomains (GridTag)
+ * - UniformGridLayout tiles/distributes the domain using a uniform rectilinear
+ *   grid of subdomains (UniformTag)
+ * - SparseTileLayout tiles/distributes the domain using non-overlapping
+ *   subdomains that need not cover the whole domain (SparseTileTag)
+ * - DynamicLayout tiles/distributes the domain using a grid partition and
+ *   handles dynamic domains such as coming from DynamicArray (DynamicTag)
+ *
+ * For actually using any of the above layout on a MultiPatch engine you need
+ * to specify appropriate grid tags which are one of those specified above
+ * amongst the layout classes.
+ *
+ * Specifying the actual tiling is done by several constructors dealing with
+ * the most important tiling types. The generic way to specify tiling is to
+ * use a partitioner, see \ref Partition for reference.
+ *
+ * Mapping the domain to the tiling can be done in two different ways,
+ * namely distributed and replicated which is specified using an instance
+ * of the DistributedTag and ReplicatedTag classes to the layout constructors.
+ * Distributed means the domain is distributed over the tiling, replicated
+ * means the entire domain is replicated over the tiling. Note that remote
+ * engines do not make sense in conjunction with replicated layouts, and this
+ * will trigger a runtime error.
+ *
+ */
diff -urN reference/main.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/main.doxygen
--- reference/main.doxygen      1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/main.doxygen  2003-10-05 
16:36:23.000000000 +0200
@@ -0,0 +1,25 @@
+/** @mainpage
+ *
+ * %Pooma reference documentation.
+ *
+ * Doxygenifized by Richard Guenther <address@hidden>
+ *
+ * Most useful is the Modules section where files and their classes
+ * are sorted by topic. Those include modules for handling the data
+ *  - \ref Array
+ *  - \ref Field
+ *  - \ref Particles
+ *
+ * and modules for specifying and organizing the problem space
+ *  - \ref Domain
+ *  - \ref Mesh
+ *  - \ref Layout
+ *  - \ref Engine
+ *
+ * Other documentation can be found beyond
+ * <A HREF="../../index.html">here</A>.
+ *
+ * %Pooma is hosted at <A 
HREF="http://www.codesourcery.com/pooma/pooma";>CodeSourcery</A>.
+ *
+ */
+
diff -urN reference/objects.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/objects.doxygen
--- reference/objects.doxygen   1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/objects.doxygen       
2003-10-05 16:37:16.000000000 +0200
@@ -0,0 +1,18 @@
+/**
+ * @defgroup Objects Data object and container classes
+ * Objects for storing data and for doing computation with.
+ *
+ * Note that for complex objects like Fields and Arrays placed inside
+ * structures the compiler will generate default copy constructors and
+ * assignment operators that usually violate the principle of least
+ * surprise in that they will invoke the objects assignment operator
+ * which will cause a PETE expression to be evaluated and this may
+ * lead to cryptic compiler error messages for for example IndexFunction
+ * engine objects. To work around this you need to explicitly provide
+ * copy constructors and assignment operators that use obj.initialize()
+ * instead of an assignment. This will catch you if you are using
+ * IndexFunction like objects, such as Stencils and FieldStencils. For
+ * writable objects be prepared to get assertion failures because of
+ * uninitialized objects created by a default constructors are later
+ * initialized by default copy/assignment.
+ */
diff -urN reference/particles.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/particles.doxygen
--- reference/particles.doxygen 1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/particles.doxygen     
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,7 @@
+/**
+ * @defgroup Particles Particles (partly pre-r2)
+ * @ingroup Objects
+ *
+ * Particles files/classes.
+ *
+ */
diff -urN reference/partition.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/partition.doxygen
--- reference/partition.doxygen 1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/partition.doxygen     
2003-10-05 16:38:10.000000000 +0200
@@ -0,0 +1,18 @@
+/**
+ * @defgroup Partition Partitioning Domains
+ * @ingroup Structuring
+ *
+ * These files deal with domain partitioning and mapping the partition
+ * to computation nodes. The following partitioners are available:
+ * - GridPartition
+ * - UniformGridPartition
+ * - TilePartition
+ *
+ * You usually don't need to interact with the mappers, which are
+ * LocalMapper, ContextMapper, BisectionMapper, ContiguousMapper,
+ * DistributedMapper and UniformMapper. They deal with mapping patches
+ * to nodes, where LocalMapper is used for ReplicatedTag tagged layouts
+ * and the others, derived from the base ContextMapper, for DistributedTag
+ * tagged layouts.
+ *
+ */
diff -urN reference/pete.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/pete.doxygen
--- reference/pete.doxygen      1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/pete.doxygen  2003-02-06 
22:30:56.000000000 +0100
@@ -0,0 +1,7 @@
+/**
+ * @defgroup PETE
+ * @ingroup Internal
+ *
+ * The PETE portable expression template engine.
+ *
+ */
diff -urN reference/pooma.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/pooma.doxygen
--- reference/pooma.doxygen     1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/pooma.doxygen 2003-02-06 
22:30:56.000000000 +0100
@@ -0,0 +1,6 @@
+/**
+ * @defgroup Pooma Pooma Headers
+ *
+ * Pooma.
+ *
+ */
diff -urN reference/threads.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/threads.doxygen
--- reference/threads.doxygen   1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/threads.doxygen       
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,11 @@
+/**
+ * @defgroup Threads
+ * @ingroup Internal
+ *
+ */
+
+/**
+ * @defgroup IterateSchedulers
+ * @ingroup Threads
+ *
+ */
diff -urN reference/tiny.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/tiny.doxygen
--- reference/tiny.doxygen      1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/tiny.doxygen  2003-02-06 
22:30:56.000000000 +0100
@@ -0,0 +1,9 @@
+/**
+ * @defgroup Tiny Primitive objects (Vector, Matrix, Tensor)
+ * @ingroup Objects
+ *
+ * Tiny classes - Vector, TinyMatrix and Tensor. These can be used as
+ * data types apart from builtin scalar types for Array and Field
+ * containers.
+ *
+ */
diff -urN reference/tulip.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/tulip.doxygen
--- reference/tulip.doxygen     1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/tulip.doxygen 2003-02-06 
22:30:56.000000000 +0100
@@ -0,0 +1,7 @@
+/**
+ * @defgroup Tulip
+ * @ingroup Internal
+ *
+ * Classes for interacting with the Cheetah messaging library.
+ *
+ */
diff -urN reference/unused.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/unused.doxygen
--- reference/unused.doxygen    1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/unused.doxygen        
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,23 @@
+/**
+ * @defgroup Unused Unused Classes/Files (pre-r2)
+ * @ingroup Internal
+ *
+ * Those include the whole CoordinateSystem/ directory.
+ *
+ */
+
+/**
+ * @defgroup CoordinateSystems Coordinate-system classes
+ * @ingroup Unused
+ *
+ * Note that support for different coordinate systems is currently not
+ * implemented. This means the current \ref Field and \ref Mesh implementations
+ * work on a %Cartesian grid only. The current implementations stem from pre-r2
+ * times.
+ *
+ * In principle here would be the implementations of the following
+ * coordinate systems:
+ * - Cartesian
+ * - Cylindrical with the 2d subsets Polar and RhoZ and the 1d subset Rho
+ * - Spherical
+ */
diff -urN reference/utility.doxygen 
/home/richard/src/pooma/cvs/r2/docs/reference/utility.doxygen
--- reference/utility.doxygen   1970-01-01 01:00:00.000000000 +0100
+++ /home/richard/src/pooma/cvs/r2/docs/reference/utility.doxygen       
2003-02-06 22:30:56.000000000 +0100
@@ -0,0 +1,7 @@
+/**
+ * @defgroup Utilities Utility Classes
+ *
+ * Random files/classes with useful stuff for either the backend or
+ * the user.
+ *
+ */