Review.

diff --git a/include/deal.II/particles/particle_handler.h b/include/deal.II/particles/particle_handler.h
index 3ea665d83cfc6b999e04809373efa7fc2b92df12..756c2998b828c74fd0e54d7db07b743cc289b790 100644 (file)
--- a/include/deal.II/particles/particle_handler.h
+++ b/include/deal.II/particles/particle_handler.h
@@ -270,6 +270,15 @@ namespace Particles
      * function on the calling mpi process, and that falls within the part of
      * triangulation owned by this mpi process.
      *
+     * The ids of the resulting particles are assigned from the optional
+     * argument @p ids. If the vector of @p ids is empty, then the ids are
+     * computed automatically from the get_next_free_particle_index() onward.
+     * For example, if the method get_next_free_particle_index() returns n0,
+     * calling this function with two MPI processes each adding n1 and n2
+     * particles will result in the n1 particles added by process zero having
+     * ids equal to `[n0,n0+n1)`, and the n2 particles added by process one
+     * having ids `[n0+n1, n0+n1+n2)`.
+     *
      * @param[in] positions A vector of points that do not need to be on the
      * local processor, but have to be in the triangulation that is associated
      * with this ParticleHandler object.
@@ -291,8 +300,9 @@ namespace Particles
      * communication intensive.
      *
      * @param[in] ids (Optional) A vector of ids to associate to each particle.
-     * If the vector is empty, the ids are computed automatically, by assigning
-     * them as a continuous range starting from first available index.
+     * If the vector is empty, the ids are assigned as a continuous range
+     * from the first available index, as documented above. If the vector is not
+     * empty, then its size must match the size of the @p positions vector.
      *
      * @return A map from owner to IndexSet, that contains the local indices
      * of the points that were passed to this function on the calling mpi
@@ -323,7 +333,7 @@ namespace Particles
      * the triangulation owned by this mpi process.
      *
      * @param[in] particles A vector of particles that do not need to be on the
-     * local processor
+     * local processor.
      *
      * @param[in] global_bounding_boxes A vector of vectors of bounding boxes.
      * The bounding boxes `global_bboxes[rk]` describe which part of the mesh is

diff --git a/source/particles/particle_handler.cc b/source/particles/particle_handler.cc
index 0f3f4274d371cac5c3a4ab731cb53240507414fa..4863d6dfe3b995d22ec2b4a8c928ab00f503b2ed 100644 (file)
--- a/source/particles/particle_handler.cc
+++ b/source/particles/particle_handler.cc
@@ -590,7 +590,7 @@ namespace Particles
 
 
     // A map from mpi process to properties, ordered as in the IndexSet.
-    // Notice that this ordering maybe different from the ordering in the
+    // Notice that this ordering may be different from the ordering in the
     // vectors above, since no local ordering is guaranteed by the
     // distribute_compute_point_locations() call.
     // This is only filled if n_global_properties is > 0
@@ -598,7 +598,7 @@ namespace Particles
       locally_owned_properties_from_other_processes;
 
     // A map from mpi process to ids, ordered as in the IndexSet.
-    // Notice that this ordering maybe different from the ordering in the
+    // Notice that this ordering may be different from the ordering in the
     // vectors above, since no local ordering is guaranteed by the
     // distribute_compute_point_locations() call.
     // This is only filled if ids.size() is > 0