added documentation

git-svn-id: https://svn.dealii.org/branches/branch_sharedtria@32739 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/include/deal.II/distributed/tria.h b/deal.II/include/deal.II/distributed/tria.h
index a54ae632678c9705888827655f6630b99cd896a2..6a465589dc15f03049485a156c96d7f9ea42ca22 100644 (file)
--- 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 0a9e97bb714f80c3869d8bc26ea017344f2baed3..3d207a3e4498dd5bfe31fc88814590a9ecf21a9c 100644 (file)
--- 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 ab0d3ed1f03c9a3da5ad150c32432034537b2e65..51ec83cc8a671517083ebe97959dc2d4c2dd5dee 100644 (file)
--- 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 ef0e929767d96b6ad5ed0bd0d67130a125a58fe6..bf59c207829e51362c09917312881cd0c6573996 100644 (file)
--- 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>