From: Timo Heister <timo.heister@gmail.com>
Date: Thu, 14 Dec 2017 03:24:02 +0000 (-0500)
Subject: document PETScWrappers::Vector constructors better
X-Git-Tag: v9.0.0-rc1~660^2~1
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e8053153d0ee76d61434437d3989bb53294211ea;p=dealii.git

document PETScWrappers::Vector constructors better
---

diff --git a/include/deal.II/lac/petsc_parallel_vector.h b/include/deal.II/lac/petsc_parallel_vector.h
index f60b268149..abab4c5f87 100644
--- a/include/deal.II/lac/petsc_parallel_vector.h
+++ b/include/deal.II/lac/petsc_parallel_vector.h
@@ -223,11 +223,16 @@ namespace PETScWrappers
                        const size_type     local_size);
 
       /**
-       * Construct a new parallel ghosted PETSc vector from an IndexSet.
-       * Note that @p local must be ascending and 1:1.
-       * The global size of the vector is determined by local.size().
-       * The global indices in @p ghost are supplied as ghost indices
-       * that can also be read locally.
+       * Construct a new parallel ghosted PETSc vector from IndexSets.
+       *
+       * Note that @p local must be ascending and 1:1, see
+       * IndexSet::is_ascending_and_one_to_one().  In particular, the DoFs in
+       * @p local need to be contiguous, meaning you can only create vectors
+       * from a DoFHandler with several finite element components if they are
+       * not reordered by component (use a PETScWrappers::BlockVector
+       * otherwise).  The global size of the vector is determined by
+       * local.size().  The global indices in @p ghost are supplied as ghost
+       * indices that can also be read locally.
        *
        * Note that the @p ghost IndexSet may be empty and that any indices
        * already contained in @p local are ignored during construction. That
@@ -244,8 +249,15 @@ namespace PETScWrappers
               const MPI_Comm &communicator);
 
       /**
-       * Construct a new parallel PETSc vector from an IndexSet. This creates
-       * a non ghosted vector.
+       * Construct a new parallel PETSc vector without ghost elements from an
+       * IndexSet.
+       *
+       * Note that @p local must be ascending and 1:1, see
+       * IndexSet::is_ascending_and_one_to_one().  In particular, the DoFs in
+       * @p local need to be contiguous, meaning you can only create vectors
+       * from a DoFHandler with several finite element components if they are
+       * not reordered by component (use a PETScWrappers::BlockVector
+       * otherwise).
        */
       explicit Vector (const IndexSet &local,
                        const MPI_Comm &communicator);