[cig-commits] [commit] master: doxygen documentation improvements and fixes (1bd4bf9)
cig_noreply at geodynamics.org
cig_noreply at geodynamics.org
Mon Jan 26 17:33:35 PST 2015
Repository : https://github.com/geodynamics/aspect
On branch : master
Link : https://github.com/geodynamics/aspect/compare/3393a76f010db2e9e3fc4ae06be1aeee36881418...9f802b89fe0a0c887376e96acaf4ccb45243610c
>---------------------------------------------------------------
commit 1bd4bf981746d7b8c6263ee42432910e7d61cbc4
Author: Timo Heister <timo.heister at gmail.com>
Date: Mon Jan 26 14:55:40 2015 -0500
doxygen documentation improvements and fixes
- add search engine
- add missing @params
- fix layout of list
- improve some documentation
- sprinkle in some const
>---------------------------------------------------------------
1bd4bf981746d7b8c6263ee42432910e7d61cbc4
doc/modules/main.h | 18 +++++++-----
doc/options.dox | 2 +-
include/aspect/boundary_composition/box.h | 14 ++-------
.../boundary_composition/initial_composition.h | 15 ++--------
include/aspect/boundary_composition/interface.h | 2 ++
.../boundary_composition/spherical_constant.h | 15 ++--------
include/aspect/introspection.h | 6 ++--
include/aspect/particle/output.h | 6 ++--
include/aspect/simulator.h | 33 ++++++++++++++++++----
source/simulator/helper_functions.cc | 20 ++++++-------
10 files changed, 67 insertions(+), 64 deletions(-)
diff --git a/doc/modules/main.h b/doc/modules/main.h
index a47f9be..204dbd9 100644
--- a/doc/modules/main.h
+++ b/doc/modules/main.h
@@ -4,11 +4,15 @@
* @image html mesh-2d-small.png
*
* This is the documentation of ASPECT, an Advanced Solver for Problems in
- * Earth's ConvecTion. The primary entry point to the documentation are - the
- * <a href="../manual.pdf">manual</a> for a broad overview; - the <a
- * href="modules.html">modules page</a> of this documentation for an overview
- * of which classes belong together in functionality; - the <a
- * href="classes.html">classes page</a> for individual classes; - the page of
- * the aspect::Simulator class for the main class of this program that drives
- * the overall algorithm.
+ * Earth's ConvecTion. The primary entry point to the documentation are
+ *
+ * - the <a href="../manual.pdf">manual</a> for a broad overview;
+ *
+ * - the <a href="modules.html">modules page</a> of this documentation for an
+ * overview of which classes belong together in functionality;
+ *
+ * - the <a href="classes.html">classes page</a> for individual classes;
+ *
+ * - the page of the aspect::Simulator class for the main class of this
+ * program that drives the overall algorithm.
*/
diff --git a/doc/options.dox b/doc/options.dox
index d962a1c..8691a26 100644
--- a/doc/options.dox
+++ b/doc/options.dox
@@ -1197,7 +1197,7 @@ MATHJAX_EXTENSIONS =
# typically be disabled. For large projects the javascript based search engine
# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution.
-SEARCHENGINE = NO
+SEARCHENGINE = YES
# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
# implemented using a PHP enabled web server instead of at the web client
diff --git a/include/aspect/boundary_composition/box.h b/include/aspect/boundary_composition/box.h
index cdfadd3..b72bf6b 100644
--- a/include/aspect/boundary_composition/box.h
+++ b/include/aspect/boundary_composition/box.h
@@ -42,18 +42,10 @@ namespace aspect
{
public:
/**
- * Return the composition that is to hold at a particular location on
- * the boundary of the domain. This function returns constant
- * compositions at the left and right boundaries.
+ * This function returns constant compositions at the left and right
+ * boundaries.
*
- * @param geometry_model The geometry model that describes the domain.
- * This may be used to determine whether the boundary composition
- * model is implemented for this geometry.
- * @param boundary_indicator The boundary indicator of the part of the
- * boundary of the domain on which the point is located at which we
- * are requesting the composition.
- * @param location The location of the point at which we ask for the
- * composition.
+ * @copydoc aspect::BoundaryComposition::Interface::composition()
*/
virtual
double composition (const GeometryModel::Interface<dim> &geometry_model,
diff --git a/include/aspect/boundary_composition/initial_composition.h b/include/aspect/boundary_composition/initial_composition.h
index 994a49a..13c7328 100644
--- a/include/aspect/boundary_composition/initial_composition.h
+++ b/include/aspect/boundary_composition/initial_composition.h
@@ -43,19 +43,10 @@ namespace aspect
{
public:
/**
- * Return the composition that is to hold at a particular location on
- * the boundary of the domain. This function returns the constant
- * compositions read from the parameter file for the inner and outer
- * boundaries.
+ * This function returns the constant compositions read from the
+ * parameter file for the inner and outer boundaries.
*
- * @param geometry_model The geometry model that describes the domain.
- * This may be used to determine whether the boundary composition
- * model is implemented for this geometry.
- * @param boundary_indicator The boundary indicator of the part of the
- * boundary of the domain on which the point is located at which we
- * are requesting the composition.
- * @param location The location of the point at which we ask for the
- * composition.
+ * @copydoc aspect::BoundaryComposition::Interface::composition()
*/
virtual
double composition (const GeometryModel::Interface<dim> &geometry_model,
diff --git a/include/aspect/boundary_composition/interface.h b/include/aspect/boundary_composition/interface.h
index 6229714..6f1a904 100644
--- a/include/aspect/boundary_composition/interface.h
+++ b/include/aspect/boundary_composition/interface.h
@@ -92,6 +92,8 @@ namespace aspect
* composition.
* @param compositional_field The number of the compositional field
* for which we are requesting the composition.
+ * @param compositional_field The index of the compositional field
+ * between 0 and @p parameters.n_compositional_fields.
*/
virtual
double composition (const GeometryModel::Interface<dim> &geometry_model,
diff --git a/include/aspect/boundary_composition/spherical_constant.h b/include/aspect/boundary_composition/spherical_constant.h
index 74ed4e0..f347dfa 100644
--- a/include/aspect/boundary_composition/spherical_constant.h
+++ b/include/aspect/boundary_composition/spherical_constant.h
@@ -42,19 +42,10 @@ namespace aspect
{
public:
/**
- * Return the composition that is to hold at a particular location on
- * the boundary of the domain. This function returns the constant
- * compositions read from the parameter file for the inner and outer
- * boundaries.
+ * This function returns the constant compositions read from the
+ * parameter file for the inner and outer boundaries.
*
- * @param geometry_model The geometry model that describes the domain.
- * This may be used to determine whether the boundary composition
- * model is implemented for this geometry.
- * @param boundary_indicator The boundary indicator of the part of the
- * boundary of the domain on which the point is located at which we
- * are requesting the composition.
- * @param location The location of the point at which we ask for the
- * composition.
+ * @copydoc aspect::BoundaryComposition::Interface::composition()
*/
virtual
double composition (const GeometryModel::Interface<dim> &geometry_model,
diff --git a/include/aspect/introspection.h b/include/aspect/introspection.h
index 54fce35..b301a50 100644
--- a/include/aspect/introspection.h
+++ b/include/aspect/introspection.h
@@ -56,9 +56,9 @@ namespace aspect
* Constructor.
* @param split_vel_pressure Set to true if velocity and pressure should
* be in separate blocks.
- * @param composition_names The names of compositional fields that will
- * be used in this simulation. This is used in initializing the fields
- * of this class.
+ * @param names_of_compositional_fields The names of compositional
+ * fields that will be used in this simulation. This is used in
+ * initializing the fields of this class.
*/
Introspection (const bool split_vel_pressure,
const std::vector<std::string> &names_of_compositional_fields);
diff --git a/include/aspect/particle/output.h b/include/aspect/particle/output.h
index 0c55405..d69a2db 100644
--- a/include/aspect/particle/output.h
+++ b/include/aspect/particle/output.h
@@ -59,8 +59,10 @@ namespace aspect
/**
* Constructor.
*
- * @param[in] The directory into which output files shall be placed.
- * @param[in] The MPI communicator that describes this simulation.
+ * @param[in] output_directory The directory into which output files
+ * shall be placed.
+ * @param[in] communicator The MPI communicator that describes this
+ * simulation.
*/
Interface(const std::string &output_directory,
const MPI_Comm communicator)
diff --git a/include/aspect/simulator.h b/include/aspect/simulator.h
index e8bb9c1..3fc4af6 100644
--- a/include/aspect/simulator.h
+++ b/include/aspect/simulator.h
@@ -883,21 +883,41 @@ namespace aspect
/**
* Fills a vector with the artificial viscosity for the temperature on
- * each local cell
+ * each local cell.
*/
void get_artificial_viscosity (Vector<float> &viscosity_per_cell) const;
/**
* Internal routine to compute the depth average of a certain quantitiy.
- * The functor @p fctr should implement: 1. bool
- * need_material_properties() 2. void setup(unsigned int q_points) 3.
- * double operator()(const MaterialModelInputs & in, const
- * MaterialModelOutputs & out, FEValues<dim> & fe_values, const
- * LinearAlgebra::BlockVector &solution, std::vector<double> & output)
+ *
+ * The functor @p fctr must be an object of a user defined type that can
+ * be arbitrary but has to satisfy certain requirements. In essence,
+ * this class type needs to implement the following interface of member
+ * functions:
+ * @code
+ * template <int dim>
+ * class Functor
+ * {
+ * public:
+ * // operator() will have @p in and @p out filled out if @p true
+ * bool need_material_properties() const;
+ *
+ * // called once at the beginning with the number of quadrature points
+ * void setup(const unsigned int q_points);
+ *
+ * // fill @p output for each quadrature point
+ * void operator()(const typename MaterialModel::Interface<dim>::MaterialModelInputs &in,
+ * const typename MaterialModel::Interface<dim>::MaterialModelOutputs &out,
+ * FEValues<dim> &fe_values,
+ * const LinearAlgebra::BlockVector &solution,
+ * std::vector<double> &output);
+ * };
+ * @endcode
*
* @param values The output vector of depth averaged values. The
* function takes the pre-existing size of this vector as the number of
* depth slices.
+ * @param fctr Instance of a class satisfying the signature above.
*/
template<class FUNCTOR>
void compute_depth_average(std::vector<double> &values,
@@ -913,6 +933,7 @@ namespace aspect
* This function is implemented in
* <code>source/simulator/helper_functions.cc</code>.
*
+ * @param advection_field Temperature or compositional field to average.
* @param values The output vector of depth averaged values. The
* function takes the pre-existing size of this vector as the number of
* depth slices.
diff --git a/source/simulator/helper_functions.cc b/source/simulator/helper_functions.cc
index b3d7cd6..4136a6d 100644
--- a/source/simulator/helper_functions.cc
+++ b/source/simulator/helper_functions.cc
@@ -963,12 +963,12 @@ namespace aspect
FunctorDepthAverageField(const FEValuesExtractors::Scalar &field)
: field_(field) {}
- bool need_material_properties()
+ bool need_material_properties() const
{
return false;
}
- void setup(unsigned int q_points)
+ void setup(const unsigned int q_points)
{
}
@@ -1006,12 +1006,12 @@ namespace aspect
class FunctorDepthAverageViscosity
{
public:
- bool need_material_properties()
+ bool need_material_properties() const
{
return true;
}
- void setup(unsigned int q_points)
+ void setup(const unsigned int q_points)
{}
void operator()(const typename MaterialModel::Interface<dim>::MaterialModelInputs &in,
@@ -1041,12 +1041,12 @@ namespace aspect
FunctorDepthAverageVelocityMagnitude(const FEValuesExtractors::Vector &field)
: field_(field) {}
- bool need_material_properties()
+ bool need_material_properties() const
{
return false;
}
- void setup(unsigned int q_points)
+ void setup(const unsigned int q_points)
{
velocity_values.resize(q_points);
}
@@ -1084,12 +1084,12 @@ namespace aspect
FunctorDepthAverageSinkingVelocity(const FEValuesExtractors::Vector &field, GravityModel::Interface<dim> *gravity)
: field_(field), gravity_(gravity) {}
- bool need_material_properties()
+ bool need_material_properties() const
{
return false;
}
- void setup(unsigned int q_points)
+ void setup(const unsigned int q_points)
{
velocity_values.resize(q_points);
}
@@ -1133,12 +1133,12 @@ namespace aspect
: material_model(mm), vs_(vs)
{}
- bool need_material_properties()
+ bool need_material_properties() const
{
return true;
}
- void setup(unsigned int q_points)
+ void setup(const unsigned int q_points)
{}
void operator()(const typename MaterialModel::Interface<dim>::MaterialModelInputs &in,
More information about the CIG-COMMITS
mailing list