From fc255b8b7353a9b4c1b80f3eee58d00b9250e1e5 Mon Sep 17 00:00:00 2001
From: "denis.davydov" <denis.davydov@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Tue, 8 Apr 2014 16:39:47 +0000
Subject: [PATCH] added documentation

git-svn-id: https://svn.dealii.org/branches/branch_sharedtria@32739 0785d39b-7218-0410-832d-ea1e28bc413d
---
 deal.II/include/deal.II/distributed/tria.h    | 25 ++++++++++++++++++-
 .../include/deal.II/dofs/dof_handler_policy.h | 25 +++++++++++++++++++
 deal.II/include/deal.II/dofs/dof_tools.h      |  6 +++++
 deal.II/include/deal.II/hp/dof_handler.h      |  2 +-
 4 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/deal.II/include/deal.II/distributed/tria.h b/deal.II/include/deal.II/distributed/tria.h
index a54ae63267..6a465589dc 100644
--- a/deal.II/include/deal.II/distributed/tria.h
+++ b/deal.II/include/deal.II/distributed/tria.h
@@ -935,6 +935,11 @@ namespace parallel
 {
   namespace shared
   {
+
+   /**
+    * This is an extension of dealii::Triangulation class to automatically
+    * partition trianguation using MPI.
+    */
     template <int dim, int spacedim = dim>
     class Triangulation : public dealii::Triangulation<dim,spacedim>
     {
@@ -952,15 +957,33 @@ namespace parallel
        */
       virtual ~Triangulation ();
 
+      /**
+       * Return locally owned subdomain id,
+       * which is equivalent to the rank of the current mpi process in
+       * communicator provided to class constructor.
+       */
       types::subdomain_id locally_owned_subdomain () const;
 
       /**
-       * Return the MPI communicator used by this triangulation.
+       * Return MPI communicator used by this triangulation.
        */
       MPI_Comm get_communicator () const;
       
+      /**
+       * Coarsen and refine the mesh according to refinement and
+       * coarsening flags set.
+       *
+       * This step is equivalent to the dealii::Triangulation class
+       * with an addition of calling dealii::GridTools::partition_triangulation() at the end.
+       */
       virtual void execute_coarsening_and_refinement ();
       
+      /**
+        * Create a triangulation.
+        *
+        * This function also partitions triangulation based on the
+        * MPI communicator provided to constructor.
+        */
       virtual void 	create_triangulation (const std::vector< Point< spacedim > > &vertices, 
       									  const std::vector< CellData< dim > > &cells, 
       									  const SubCellData &subcelldata);
diff --git a/deal.II/include/deal.II/dofs/dof_handler_policy.h b/deal.II/include/deal.II/dofs/dof_handler_policy.h
index 0a9e97bb71..3d207a3e44 100644
--- a/deal.II/include/deal.II/dofs/dof_handler_policy.h
+++ b/deal.II/include/deal.II/dofs/dof_handler_policy.h
@@ -133,20 +133,45 @@ namespace internal
                        NumberCache & number_cache) const;
       };
 
+      /**
+        * This class implements the
+        * policy for operations when
+        * we use a
+        * parallel::shared::Triangulation
+        * object.
+        */
       template <int dim, int spacedim>
       class ParallelShared : public Sequential<dim,spacedim>
       {
       public:
+
+    	  /**
+    	    * Distribute degrees of freedom on
+    	    * the object given as first argument.
+    	    *
+    	    * On distribution, DoFs are renumbered subdomain-wise and
+    	    * number_cache.n_locally_owned_dofs_per_processor[i] and
+    	    * number_cache.locally_owned_dofs are updated consistently.
+    	    */
     	  virtual
     	  void
     	  distribute_dofs (dealii::DoFHandler<dim,spacedim> &dof_handler,
     			           NumberCache & number_cache) const;
 
+    	  /**
+    	   * This function is not yet implemented.
+    	   */
     	  virtual
     	  void
     	  distribute_mg_dofs (dealii::DoFHandler<dim,spacedim> &dof_handler,
     	                      std::vector<NumberCache> &number_caches) const;
 
+    	  /**
+    	    * Renumber degrees of freedom as
+    	    * specified by the first argument.
+    	    *
+    	    * On renumbering, number_cache.locally_owned_dofs is updated consistently.
+    	    */
     	  virtual
     	  void
     	  renumber_dofs (const std::vector<types::global_dof_index>  &new_numbers,
diff --git a/deal.II/include/deal.II/dofs/dof_tools.h b/deal.II/include/deal.II/dofs/dof_tools.h
index ab0d3ed1f0..51ec83cc8a 100644
--- a/deal.II/include/deal.II/dofs/dof_tools.h
+++ b/deal.II/include/deal.II/dofs/dof_tools.h
@@ -1372,6 +1372,12 @@ namespace DoFTools
   extract_locally_relevant_dofs (const DH &dof_handler,
                                  IndexSet &dof_set);
 
+  /**
+   * Extract the set of global DoF indices distributed on
+   * cells with the given subdomain id. This function should be used for
+   * DoFHandler objects built on dealii::Triangulation or parallel::shared::Triangulation
+   * classes. Internally the funciton is based on DoFTools::get_subdomain_association.
+   */
   template <class DH>
   IndexSet
   locally_owned_dofs_with_subdomain (const DH                  &dof_handler,
diff --git a/deal.II/include/deal.II/hp/dof_handler.h b/deal.II/include/deal.II/hp/dof_handler.h
index ef0e929767..bf59c20782 100644
--- a/deal.II/include/deal.II/hp/dof_handler.h
+++ b/deal.II/include/deal.II/hp/dof_handler.h
@@ -26,7 +26,7 @@
 #include <deal.II/dofs/function_map.h>
 #include <deal.II/dofs/dof_iterator_selector.h>
 #include <deal.II/dofs/number_cache.h>
-//#include <deal.II/dofs/dof_tools.h>
+//#include <deal.II/dofs/dof_tools.h> //TODO: circular inclusion problems
 #include <deal.II/hp/fe_collection.h>
 
 #include <vector>
-- 
2.39.5