From fcb93cf171dd9e2ddac922a88087bff4a9ad2969 Mon Sep 17 00:00:00 2001
From: bangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Fri, 11 Jul 2014 02:42:25 +0000
Subject: [PATCH] Update documentation in a couple of places. Remove some code
 duplication.

git-svn-id: https://svn.dealii.org/trunk@33132 0785d39b-7218-0410-832d-ea1e28bc413d
---
 .../deal.II/multigrid/mg_constrained_dofs.h   | 67 +++++++++----------
 deal.II/include/deal.II/multigrid/mg_tools.h  | 32 ++++-----
 2 files changed, 43 insertions(+), 56 deletions(-)

diff --git a/deal.II/include/deal.II/multigrid/mg_constrained_dofs.h b/deal.II/include/deal.II/multigrid/mg_constrained_dofs.h
index 9d528f1204..e30bfa3ae4 100644
--- a/deal.II/include/deal.II/multigrid/mg_constrained_dofs.h
+++ b/deal.II/include/deal.II/multigrid/mg_constrained_dofs.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 2010 - 2013 by the deal.II authors
+// Copyright (C) 2010 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -43,25 +43,24 @@ public:
 
   typedef std::vector<std::set<types::global_dof_index> >::size_type size_dof;
   /**
-   * Fill the internal data
-   * structures with values
-   * extracted from the dof
-   * handler.
+   * Fill the internal data structures with values extracted from the dof
+   * handler object.
    *
-   * This function leaves
-   * #boundary_indices empty, since
-   * no boundary values are
-   * provided.
+   * This function ensures that on every level, degrees of freedom at interior
+   * edges of a refinement level are treated corrected but leaves degrees of
+   * freedom at the boundary of the domain untouched assuming that no
+   * Dirichlet boundary conditions for them exist.
    */
   template <int dim, int spacedim>
-  void initialize(const DoFHandler<dim,spacedim> &dof);
+  void initialize (const DoFHandler<dim,spacedim> &dof);
 
   /**
-   * Fill the internal data
-   * structures with values
-   * extracted from the dof
-   * handler, applying the boundary
-   * values provided.
+   * Fill the internal data structures with values extracted from the dof
+   * handler object and apply the boundary values provided.
+   *
+   * This function internally calls the initialize() function above and the
+   * constrains degrees on the external boundary of the domain by calling
+   * MGTools::make_boundary_list() with the given second and third argument.
    */
   template <int dim, int spacedim>
   void initialize(const DoFHandler<dim,spacedim> &dof,
@@ -75,7 +74,7 @@ public:
 
   /**
    * Determine whether a dof index is subject to a boundary
-   * constraint. (is on boundary of domain)
+   * constraint. (In other words, whether it is on boundary of domain.)
    */
   bool is_boundary_index (const unsigned int level,
                           const types::global_dof_index index) const;
@@ -192,15 +191,21 @@ void
 MGConstrainedDoFs::initialize(const DoFHandler<dim,spacedim> &dof)
 {
   const unsigned int nlevels = dof.get_tria().n_global_levels();
+
+  boundary_indices.resize(nlevels);
+
   refinement_edge_indices.resize(nlevels);
   refinement_edge_boundary_indices.resize(nlevels);
   refinement_edge_indices_old.clear();
   refinement_edge_boundary_indices_old.clear();
   for (unsigned int l=0; l<nlevels; ++l)
     {
+      boundary_indices[l].clear();
+
       refinement_edge_indices[l] = IndexSet(dof.n_dofs(l));
       refinement_edge_boundary_indices[l] = IndexSet(dof.n_dofs(l));
     }
+  
   MGTools::extract_inner_interface_dofs (dof, refinement_edge_indices,
                                          refinement_edge_boundary_indices);
 }
@@ -209,28 +214,16 @@ MGConstrainedDoFs::initialize(const DoFHandler<dim,spacedim> &dof)
 template <int dim, int spacedim>
 inline
 void
-MGConstrainedDoFs::initialize(
-  const DoFHandler<dim,spacedim> &dof,
-  const typename FunctionMap<dim>::type &function_map,
-  const ComponentMask &component_mask)
+MGConstrainedDoFs::initialize(const DoFHandler<dim,spacedim> &dof,
+			      const typename FunctionMap<dim>::type &function_map,
+			      const ComponentMask &component_mask)
 {
-  const unsigned int nlevels = dof.get_tria().n_global_levels();
-  boundary_indices.resize(nlevels);
-  refinement_edge_indices.resize(nlevels);
-  refinement_edge_boundary_indices.resize(nlevels);
-  refinement_edge_indices_old.clear();
-  refinement_edge_boundary_indices_old.clear();
-
-  for (unsigned int l=0; l<nlevels; ++l)
-    {
-      boundary_indices[l].clear();
-      refinement_edge_indices[l] = IndexSet(dof.n_dofs(l));
-      refinement_edge_boundary_indices[l] = IndexSet(dof.n_dofs(l));
-    }
-
-  MGTools::make_boundary_list (dof, function_map, boundary_indices, component_mask);
-  MGTools::extract_inner_interface_dofs (dof, refinement_edge_indices,
-                                         refinement_edge_boundary_indices);
+  initialize (dof);
+  
+  MGTools::make_boundary_list (dof,
+			       function_map,
+			       boundary_indices,
+			       component_mask);
 }
 
 
diff --git a/deal.II/include/deal.II/multigrid/mg_tools.h b/deal.II/include/deal.II/multigrid/mg_tools.h
index bb2b9b08d1..143bffb746 100644
--- a/deal.II/include/deal.II/multigrid/mg_tools.h
+++ b/deal.II/include/deal.II/multigrid/mg_tools.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 2005 - 2013 by the deal.II authors
+// Copyright (C) 2005 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -213,26 +213,20 @@ namespace MGTools
                             std::vector<unsigned int> target_component) DEAL_II_DEPRECATED;
 
   /**
-   * Generate a list of those
-   * degrees of freedom at the
-   * boundary which should be
-   * eliminated from the matrix.
+   * Generate a list of those degrees of freedom at the boundary of the domain
+   * that should be eliminated from the matrix because they will be
+   * constrained by Dirichlet boundary conditions.
    *
-   * This is the multilevel
-   * equivalent of
-   * VectorTools::interpolate_boundary_values,
-   * but since the multilevel
-   * method does not have its own
-   * right hand side, the function
-   * values are ignored.
+   * This is the multilevel equivalent of
+   * VectorTools::interpolate_boundary_values, but since the multilevel method
+   * does not have its own right hand side, the function values returned by
+   * the function object that is part of the function_map argument are
+   * ignored.
    *
-   * @arg <tt>boundary_indices</tt>
-   * is a vector which on return
-   * contains all indices of
-   * boundary constraint degrees of
-   * freedom for each level. Its
-   * length has to match the number
-   * of levels.
+   * @arg <tt>boundary_indices</tt> is a vector which on return contains all
+   * indices of degrees of freedom for each level that are at the part of the
+   * boundary identified by the function_map argument. Its length has to match
+   * the number of levels in the dof handler object.
    */
   template <int dim, int spacedim>
   void
-- 
2.39.5