Correct documentation. Provide a glossary entry and link to it.

git-svn-id: https://svn.dealii.org/trunk@25589 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h
index 797fed3e12e58f50811681c977c9f2068380021e..71619f7051019215a7001955ca17bca023825520 100644 (file)
--- a/deal.II/doc/doxygen/headers/glossary.h
+++ b/deal.II/doc/doxygen/headers/glossary.h
@@ -269,6 +269,41 @@
  * FiniteElement and FEValues classes.</dd>
  *
  *
+ * <dt class="glossary">@anchor GlossComponentMask <b>Component mask</b></dt>
+ *
+ * <dd>
+ * When using vector-valued elements (see @ref vector_valued) to solve systems
+ * of equations, one frequently wants to restrict some operations to only certain
+ * solution variables. For example, when solving the Stokes equations, one may
+ * wish to only interpolate boundary values for the velocity components
+ * but not the pressure. In deal.II, this is typically done by passing functions
+ * a <i>component mask</i>. Component masks are always specified as a
+ * <code>std::vector@<bool@></code>, i.e., an array with as many entries as the
+ * finite element has components (e.g., in the Stokes case, there are
+ * <code>dim+1</code> components) and where each entry is either true or false.
+ * In the example where we would like to interpolate boundary values only for
+ * the velocity components of the Stokes system, this component mask would then
+ * be <code>[true, true, false]</code> in 2d and <code>[true, true, true, false]</code>
+ * in 3d to indicate that no boundary values shall be set for the pressure variable
+ * (the last of the <code>dim+1</code> vector components of the solution.
+ *
+ * There are many functions that take such component masks, for example
+ * DoFTools::make_zero_boundary_values,
+ * VectorTools::interpolate_boundary_values,
+ * KellyErrorEstimator::estimate, etc. In some cases, there are multiple
+ * functions with these names but only some of them have a component mask
+ * argument.
+ *
+ * Many of the functions that take a component mask accept a vector of length
+ * zero to indicate <i>all components</i>, i.e., as if the vector had the
+ * correct length and was filled with only <code>true</code> values. The reason
+ * is that the empty vector can be constructed in place using the code snippet
+ * <code>std::vector@<bool@>()</code> and can thus be used as a default
+ * argument in function signatures.
+ * </dd>
+ *
+ *
+ *
  * <dt class="glossary">@anchor GlossCompress <b>Compressing distributed
  *                                              vectors and matrices</b></dt>
  *

diff --git a/deal.II/include/deal.II/dofs/dof_tools.h b/deal.II/include/deal.II/dofs/dof_tools.h
index 2d33d4ad62b59db2173832bc19f2e860543a6a40..108b098e1ab86a4a3272b09dec8c93291c104f63 100644 (file)
--- a/deal.II/include/deal.II/dofs/dof_tools.h
+++ b/deal.II/include/deal.II/dofs/dof_tools.h
@@ -985,7 +985,8 @@ namespace DoFTools
                                     * as being constrained.
                                     *
                                     * The flags in the last parameter,
-                                    * @p component_mask denote which
+                                    * @p component_mask (see @ref GlossComponentMask)
+                                    * denote which
                                     * components of the finite element space
                                     * shall be constrained with periodic
                                     * boundary conditions. If it is left as
@@ -1063,7 +1064,8 @@ namespace DoFTools
                                     * marked as being constrained.
                                     *
                                     * The flags in the last parameter,
-                                    * @p component_mask denote which
+                                    * @p component_mask (see @ref GlossComponentMask)
+                                    * denote which
                                     * components of the finite element space
                                     * shall be constrained with periodic
                                     * boundary conditions. If it is left as
@@ -2579,6 +2581,11 @@ namespace DoFTools
                                     * one of its nonzero components
                                     * is affected.
                                     *
+                                    * The last argument indicates which
+                                    * components of the solution
+                                    * vector should be constrained to zero
+                                    * (see @ref GlossComponentMask).
+                                    *
                                     * This function is used
                                     * in step-36, for
                                     * example.

diff --git a/deal.II/include/deal.II/numerics/error_estimator.h b/deal.II/include/deal.II/numerics/error_estimator.h
index 61ea08138a895b7ab1e278bdc4677da0a0d56483..ba847adb88644faa77d7094aded247a4e6e310b1 100644 (file)
--- a/deal.II/include/deal.II/numerics/error_estimator.h
+++ b/deal.II/include/deal.II/numerics/error_estimator.h
@@ -254,7 +254,9 @@ class KellyErrorEstimator
                                       * vector-valued. You then have
                                       * to set those entries to true
                                       * in the bit-vector
-                                      * @p component_mask for which the
+                                      * @p component_mask
+                                      * (see @ref GlossComponentMask)
+                                      * for which the
                                       * respective component is to be
                                       * used in the error
                                       * estimator. The default is to

diff --git a/deal.II/include/deal.II/numerics/vectors.h b/deal.II/include/deal.II/numerics/vectors.h
index 0852961cf741c8150bc541ccced1c64edc26f9e9..5e81be22516f69496887dc1d3dd8721da27458e7 100644 (file)
--- a/deal.II/include/deal.II/numerics/vectors.h
+++ b/deal.II/include/deal.II/numerics/vectors.h
@@ -686,11 +686,16 @@ namespace VectorTools
                                     * map of boundary values.
                                     *
                                     * The parameter
-                                    * @p boundary_component
-                                    * corresponds to the number
+                                    * @p function_map argument
+                                    * provides a list of boundary
+                                    * indicators to be handled by
+                                    * this function and corresponding
+                                    * boundary value functions. The
+                                    * keys of this map
+                                    * correspond to the number
                                     * @p boundary_indicator of the
                                     * face.  types::internal_face_boundary_id
-                                    * is an illegal value, since
+                                    * is an illegal value for this key since
                                     * it is reserved for interior faces.
                                     *
                                     * The flags in the last
@@ -712,6 +717,7 @@ namespace VectorTools
                                     * boundary function will be used
                                     * for which the respective flag
                                     * was set in the component mask.
+                                    * See also @ref GlossComponentMask.
                                     *
                                     * It is assumed that the number
                                     * of components of the function
@@ -844,7 +850,8 @@ namespace VectorTools
                                     * reserved for interior faces.
                                     *
                                     * The flags in the last parameter, @p
-                                    * component_mask denote which
+                                    * component_mask (see @ref GlossComponentMask)
+                                    * denote which
                                     * components of the finite element
                                     * space shall be interpolated. If it
                                     * is left as specified by the default