[RFC] Preparing reference manual merge
Richard Guenther
rguenth at tat.physik.uni-tuebingen.de
Thu Jan 16 20:07:39 UTC 2003
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 ¢ering, 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:
More information about the pooma-dev
mailing list