[RFC] Preparing reference manual merge

[Richard Guenther]

Hi!

I'd like starting to merge support for doxygen to create a reference
manual for pooma. For the results you can view

http://www.tat.physik.uni-tuebingen.de/~rguenth/pooma/reference/

There are a few new files to be placed at a sensible location and a
location to be choosen for the reference documentation. I'd suggest
creating a docs/reference directory and place doxygen.conf, a Makefile
and all summary documentation there. The generated html documentation
would go to docs/reference/html.

Any other/better suggestions?

Now to the merge itself (source file comments need to be changed). I have
patches that
- add per-file documentation (@file)
- change class/function documentation to be recognized by doxygen
  (for class documentation I chose /** */ style, for methods/types/etc.
   /// style)

A typical diff would look like the one below. I just like people
to give comments to the style so I can try to improve it.

Of course there is the possibility that a merge of these changes is not
appreciated, if this is the case I'd like to hear that, too, of course.

Thanks for your time,

Richard.


===== Field.h 1.1 vs edited =====
--- 1.1/r2/src/Field/Field.h    Mon May 13 17:47:35 2002
+++ edited/Field.h      Thu Jan 16 20:46:37 2003
@@ -34,12 +34,11 @@
 #ifndef POOMA_FIELD_FIELD_H
 #define POOMA_FIELD_FIELD_H

-//-----------------------------------------------------------------------------
-// Overview:
-//
-// Field
-//   - ties together the notions of field-category and mesh.
-//-----------------------------------------------------------------------------
+/** @file
+ * @ingroup Field
+ * @brief
+ *   ties together the notions of field-category and mesh.
+ */

 //-----------------------------------------------------------------------------
 // Includes:
@@ -104,6 +103,7 @@
 class FieldOffsetList;

 //-----------------------------------------------------------------------------
+/** @name assign
 // Prototypes for the assign function used to assign an expression to a Field.
 //
 // Prototypes defined here:
@@ -120,8 +120,11 @@
 //
 // where "yourclass" is the class that you would like to work on the
 // right-hand side in an expression with a Field on the left-hand side.
+*/
 //-----------------------------------------------------------------------------
-
+
+//@{
+
 template<class Mesh, class T, class EngineTag,
   class MeshTag2, class T2, class EngineTag2, class Op>
 const Field<Mesh, T, EngineTag> &
@@ -146,9 +149,13 @@
 assign(const Array<Dim2, T2, EngineTag2> &lhs,
        const Field<Mesh, T, EngineTag> &rhs, const Op &op);

+//@}
+
 //-----------------------------------------------------------------------------
+/**
 // SubFieldView is used to implement the syntax f[i], which selects the
 // ith SubField for field f.
+*/
 //-----------------------------------------------------------------------------

 struct SubFieldViewFunctorTag;
@@ -241,12 +248,14 @@


 //-----------------------------------------------------------------------------
+/**
 // View1Implementation<Field, D, SV> specialization for indexing a field
 // with a single domain. There is a single-valued version (SV == true)
 // and a multi-valued version (SV == false).
 //
 // Any changes to View1Implementation should also be made to
 // AltView1Implementation.
+*/
 //-----------------------------------------------------------------------------

 // Single-valued version. Handles scalars and Locs.
@@ -483,11 +492,13 @@


 //-----------------------------------------------------------------------------
+/**
 // AltView1Implementation avoids an instantiation problem that arises when two
 // classes use each other.  This class's definition should be exactly
 // the same as View1Implementation except omitting member functions.
 //
 // Do NOT explicitly instantiate this class.
+*/
 //-----------------------------------------------------------------------------

 // Single-valued version. Handles scalars and Locs.
@@ -536,9 +547,11 @@


 //-----------------------------------------------------------------------------
+/**
 // View1<Field, S1> specialization for indexing a field with a single domain.
 //
 // Any changes to View1 should also be made to AltView1.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag, class Sub1>
@@ -587,9 +600,11 @@


 //-----------------------------------------------------------------------------
+/**
 // View1<Field, int> specialization for indexing a field with an int.
 //
 // Any changes to View1 should also be made to AltView1.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag>
@@ -633,11 +648,13 @@


 //-----------------------------------------------------------------------------
+/**
 // AltView1 avoids an instantiation problem that arises when two
 // classes use each other.  This class's definition should be exactly
 // the same as View1 except omitting member functions.
 //
 // Do NOT explicitly instantiate this class.
+*/
 //-----------------------------------------------------------------------------

 template<class FieldTag, class DomainTag>
@@ -675,11 +692,13 @@


 //-----------------------------------------------------------------------------
+/**
 // AltView1 avoids an instantiation problem that arises when two
 // classes use each other.  This class's definition should be exactly
 // the same as View1 except omitting member functions.
 //
 // Do NOT explicitly instantiate this class.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag>
@@ -698,8 +717,10 @@


 //-----------------------------------------------------------------------------
+/**
 // View2<Field, S1, S2> specialization for indexing a field with two
 // domains.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag,
@@ -747,8 +768,10 @@


 //-----------------------------------------------------------------------------
+/**
 // View2<Field, int, int> specialization for indexing a field with two
 // integers.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag>
@@ -792,8 +815,10 @@


 //-----------------------------------------------------------------------------
+/**
 // View2<Field, FieldOffset<Dim>, Loc<Dim> > specialization for
 // indexing a field with a FieldOffset and a Loc.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag, int Dim>
@@ -865,8 +890,10 @@


 //-----------------------------------------------------------------------------
+/**
 // View3<Field, S1, S2, S3> specialization for indexing a field with three
 // domains.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag,
@@ -916,8 +943,10 @@


 //-----------------------------------------------------------------------------
+/**
 // View3<Field, int, int, int> specialization for indexing a field with three
 // integers.
+*/
 //-----------------------------------------------------------------------------

 template<class Mesh, class T, class EngineTag>
@@ -1066,7 +1095,7 @@


 //-----------------------------------------------------------------------------
-// Field.
+/// Field.
 //-----------------------------------------------------------------------------

 template<class Mesh,
@@ -1078,74 +1107,75 @@
   //---------------------------------------------------------------------------
   // Exported typedefs and enumerations.

-  // The specification type.
+  /// The specification type.

   typedef Mesh MeshTag_t;
   typedef Mesh Mesh_t;

-  // The type.
+  /// The type.

   typedef T T_t;

-  // The engine tag.
+  /// The engine tag.

   typedef EngineTag EngineTag_t;

-  // This class.
+  /// This class.

   typedef Field<Mesh, T, EngineTag> This_t;

-  // The field engine type.
+  /// The field engine type.

   typedef FieldEngine<Mesh, T, EngineTag> FieldEngine_t;

-  // The dimension (i.e., the number of indices required to select a point).
+  /// The dimension (i.e., the number of indices required to select a point).

   enum { dimensions = FieldEngine_t::dimensions };

-  // The engine type.
+  /// The engine type.

   typedef Engine<dimensions, T, EngineTag> Engine_t;

-  // Element_t is the type of elements managed by this field's engine.
-  // ElementRef_t is the writable version.
-
+  /// Element_t is the type of elements managed by this field's engine.
   typedef typename Engine_t::Element_t Element_t;
+  /// ElementRef_t is the writable version.
   typedef typename Engine_t::ElementRef_t ElementRef_t;

-  // Layout_t is the Engine's layout.
+  /// Layout_t is the Engine's layout.

   typedef typename Engine_t::Layout_t Layout_t;

-  // The types of the our domains.
+  /// The types of the our domains.

   typedef typename Engine_t::Domain_t Domain_t;

-  // The types of the our centering.
+  /// The types of the our centering.

   typedef Centering<dimensions> Centering_t;

   //---------------------------------------------------------------------------
-  // User-callable constructors. These ctors are meant to be called by users.
-
-  // Mesh/centering/layout constructors. We use the specified mesh
-  // object to initialize our mesh and the layout to initialize
-  // the engines. Clearly, these must be synchronized. This is appropriate
-  // for multi-patch engines. We just store the centering.
+  /// @name User-callable constructors
+  /// These ctors are meant to be called by users.
+  //@{
+
+  /// Mesh/centering/layout constructors. We use the specified mesh
+  /// object to initialize our mesh and the layout to initialize
+  /// the engines. Clearly, these must be synchronized. This is appropriate
+  /// for multi-patch engines. We just store the centering.

   Field()
   : fieldEngine_m()
     { }

-  // This version is used for expressions.
+  /// This version is used for expressions.

   template<class I1>
   explicit Field(const I1 &i1)
     : fieldEngine_m(i1)
   { }

-  // Layout is templated so you can use a compatible layout to construct the
-  // engine.
+  /// Layout is templated so you can use a compatible layout to construct the
+  /// engine.

   template<class Layout2>
   Field(const Centering_t &centering, const Layout2 &layout, const Mesh_t 
&mesh)
@@ -1172,20 +1202,20 @@
     : fieldEngine_m(centering, layout, Mesh_t(layout, i1, i2), materials)
   { }

-  // Copy constructor.
+  /// Copy constructor.

   Field(const This_t &model)
   : fieldEngine_m(model.fieldEngine())
   { }

-  // Copy initializer.
+  /// Copy initializer.

   void initialize(const This_t &model)
   {
     fieldEngine_m = model.fieldEngine();
   }

-  // Initializers that are equivalent to the constructors.
+  /// Initializers that are equivalent to the constructors.

   template<class Layout2>
   void
@@ -1209,12 +1239,16 @@
     fieldEngine_m = FieldEngine_t(centering, layout, Mesh_t(layout));
   }

+  //@}
+
   //---------------------------------------------------------------------------
-  // Internal POOMA constructors. These ctors are used internally by POOMA.
-  // They are not really meant to be called by users.
+  /// @name Internal POOMA constructors
+  /// These ctors are used internally by POOMA.
+  /// They are not really meant to be called by users.
+  //@{

-  // Model-initializer constructor. Used by SubFieldView and
-  // View1Implementation above and by MakeFieldReturn in FieldCreateLeaf.h.
+  /// Model-initializer constructor. Used by SubFieldView and
+  /// View1Implementation above and by MakeFieldReturn in FieldCreateLeaf.h.

   template<class GT2, class T2, class ET2, class Initializer>
   Field(const Field<GT2, T2, ET2> &model, const Initializer &i)
@@ -1232,13 +1266,15 @@
   { }

   //---------------------------------------------------------------------------
-  // Empty destructor is fine for us.
+  /// Empty destructor is fine for us.

   ~Field() { }

+  //@}

   //---------------------------------------------------------------------------
-  // Accessors.
+  /// @name Accessors
+  //@{

   inline const Engine_t &engine() const
     {
@@ -1330,11 +1366,13 @@
   {
     return fieldEngine_m.engine().layout();
   }
+
+  //@}

   //---------------------------------------------------------------------------
-  // Instruct the field to make its own copy of its data.
-  // Recursively call ourself with subfield views of this field. When we're
-  // through, tell the fieldEngine to make a distinct copy of itself.
+  /// Instruct the field to make its own copy of its data.
+  /// Recursively call ourself with subfield views of this field. When we're
+  /// through, tell the fieldEngine to make a distinct copy of itself.

   void makeOwnCopy()
   {
@@ -1345,10 +1383,10 @@


   //---------------------------------------------------------------------------
-  // Sub-field view creation function.
-  // A field consists of (potentially) several sub-fields. This function
-  // returns a view of one of these.
-
+  /// @name Sub-field view creation functions
+  /// A field consists of (potentially) several sub-fields. This function
+  /// returns a view of one of these.
+  //@{
   inline typename SubFieldView<This_t>::Type_t
   operator[](int iSubfield) const
     {
@@ -1377,13 +1415,16 @@
     typedef SubFieldView<This_t> Ret_t;
     return Ret_t::make(*this, m);
   }
+  //@}

   //---------------------------------------------------------------------------
-  // View-creation operations. These operator() and read() functions take
-  // zero or more sub-domains, which combine to form a domain with
-  // dimensionality identical to the rank of the field. The zero argument
-  // version returns a view of the physical domain and the 'All'-suffixed
-  // versions return a view of the total domain.
+  /// @name View-creation operations
+  /// These operator() and read() functions take
+  /// zero or more sub-domains, which combine to form a domain with
+  /// dimensionality identical to the rank of the field. The zero argument
+  /// version returns a view of the physical domain and the 'All'-suffixed
+  /// versions return a view of the total domain.
+  //@{

   inline typename AltView1<This_t, Domain_t>::ReadType_t
   read() const
@@ -1460,11 +1501,13 @@
       typedef View3<This_t, Sub1, Sub2, Sub3> Ret_t;
       return Ret_t::make(*this, s1, s2, s3);
     }
-
+  //@}

   //---------------------------------------------------------------------------
-  // Component-forwarding functions. These work quite similarly to the
-  // ones from Array except we produce a Field with the same Mesh.
+  /// @name Component-forwarding functions
+  /// These work quite similarly to the
+  /// ones from Array except we produce a Field with the same Mesh.
+  //@{

   inline typename ComponentView<Loc<1>, This_t>::Type_t
   comp(const int &i1) const
@@ -1484,11 +1527,11 @@
   {
     return ComponentView<Components, This_t>::make(*this, loc);
   }
-
+  //@}

   //---------------------------------------------------------------------------
-  // Patch accessor functions returns the i'th patch.
-
+  /// @name Patch accessor functions returns the i'th patch.
+  //@{
   inline typename Patch<This_t>::Type_t
   patchLocal(EnginePatch::PatchID_t i) const
     {
@@ -1500,14 +1543,17 @@
   {
     return engineFunctor(engine(), EngineNumPatches());
   }
+  //@}

   //---------------------------------------------------------------------------
-  // Copy assignment operators. We pack this assignment expression into a
-  // PETE binary expression tree node and then use this to construct an
-  // array with an expression engine. We then pass this on to an evaluator,
-  // which handles the computation. The first three versions handle assigning
-  // Arrays and ConstArrays to Arrays and the fourth one handles assigning
-  // scalars.
+  /// @name Copy assignment operators
+  /// We pack this assignment expression into a
+  /// PETE binary expression tree node and then use this to construct an
+  /// array with an expression engine. We then pass this on to an evaluator,
+  /// which handles the computation. The first three versions handle assigning
+  /// Arrays and ConstArrays to Arrays and the fourth one handles assigning
+  /// scalars.
+  //@{

   This_t &operator=(const This_t &rhs)
     {
@@ -1526,11 +1572,13 @@
       return assign(*this, rhs, OpAssign());
     }

+  //@}

   //---------------------------------------------------------------------------
-  // Op-assignment operators.
+  /// @name Op-assignment operators
+  //@{

-  // Addition.
+  /// Addition.

   template<class T1>
   const This_t &operator+=(const T1 &rhs) const
@@ -1538,7 +1586,7 @@
       return assign(*this, rhs, OpAddAssign());
     }

-  // Subtraction.
+  /// Subtraction.

   template<class T1>
   const This_t &operator-=(const T1 &rhs) const
@@ -1546,7 +1594,7 @@
       return assign(*this, rhs, OpSubtractAssign());
     }

-  // Multiplication.
+  /// Multiplication.

   template<class T1>
   const This_t &operator*=(const T1 &rhs) const
@@ -1554,7 +1602,7 @@
       return assign(*this, rhs, OpMultiplyAssign());
     }

-  // Division.
+  /// Division.

   template<class T1>
   const This_t &operator/=(const T1 &rhs) const
@@ -1562,7 +1610,7 @@
       return assign(*this, rhs, OpDivideAssign());
     }

-  // Modulus.
+  /// Modulus.

   template<class T1>
   const This_t &operator%=(const T1 &rhs) const
@@ -1570,7 +1618,7 @@
       return assign(*this, rhs, OpModAssign());
     }

-  // Bitwise-Or.
+  /// Bitwise-Or.

   template<class T1>
   const This_t &operator|=(const T1 &rhs) const
@@ -1578,7 +1626,7 @@
       return assign(*this, rhs, OpBitwiseOrAssign());
     }

-  // Bitwise-And.
+  /// Bitwise-And.

   template<class T1>
   const This_t &operator&=(const T1 &rhs) const
@@ -1586,7 +1634,7 @@
       return assign(*this, rhs, OpBitwiseAndAssign());
     }

-  // Bitwise-Xor.
+  /// Bitwise-Xor.

   template<class T1>
   const This_t &operator^=(const T1 &rhs) const
@@ -1594,7 +1642,7 @@
       return assign(*this, rhs, OpBitwiseXorAssign());
     }

-  // Left shift.
+  /// Left shift.

   template<class T1>
   const This_t &operator<<=(const T1 &rhs) const
@@ -1602,7 +1650,7 @@
       return assign(*this, rhs, OpLeftShiftAssign());
     }

-  // Right shift.
+  /// Right shift.

   template<class T1>
   const This_t &operator>>=(const T1 &rhs) const
@@ -1610,17 +1658,21 @@
       return assign(*this, rhs, OpRightShiftAssign());
     }

+  //@}

   //---------------------------------------------------------------------------
-  // Relation support.
-
+  /// @name Relation support
+  //@{
+
+  /// add a relation
   void addRelation(RelationListItem *item) const
   {
     PAssert(numSubFields() == 0);

     fieldEngine_m.relations().addRelation(item);
   }
-
+
+  /// remove all relations
   void removeRelations()
   {
     for (int m = 0; m < numMaterials(); ++m)
@@ -1631,7 +1683,8 @@
       }
     }
   }
-
+
+  /// trigger all relations dirty (or all, if makeDirty is set)
   void applyRelations(bool makeDirty = false) const
   {
     for (int m = 0; m < numMaterials(); ++m)
@@ -1644,7 +1697,8 @@
       }
     }
   }
-
+
+  /// dirty field, dirtying all relations
   void setDirty() const
   {
     for (int m = 0; m < numMaterials(); ++m)
@@ -1655,7 +1709,8 @@
       }
     }
   }
-
+
+  /// clear dirty flag of field, clearing all relations dirty flag
   void clearDirty() const
   {
     for (int m = 0; m < numMaterials(); ++m)
@@ -1667,6 +1722,7 @@
     }
   }

+  //@}

 private: