Make the descriptions clearer

diff --git a/include/deal.II/particles/particle_accessor.h b/include/deal.II/particles/particle_accessor.h
index 70103e3754a061d757519502a09cf287a01c1dd9..48f3d339318983c5fcb14fb69fd165864f748c23 100644 (file)
--- a/include/deal.II/particles/particle_accessor.h
+++ b/include/deal.II/particles/particle_accessor.h
@@ -135,13 +135,18 @@ namespace Particles
      * enables the direct array access (similar to
      * LinearAlgebra::distributed::Vector::local_element()) to quantities used
      * for local computations. Use
-     * ParticleHandler::get_max_local_particle_index() to query the largest
-     * index for suitable array sizes.
+     * ParticleHandler::get_max_local_particle_index() to query suitable array
+     * sizes.
      *
      * @note The number returned by this function is not stable between calls
      * of ParticleHandler::sort_particles_into_subdomains_and_cells() and
-     * therefore it cannot be used to track quantities across those calls. Use
-     * particle properties for storing persistent information.
+     * therefore it cannot be used to track quantities across those
+     * calls. Furthermore, the numbers returned by this function are typically
+     * not refreshed in case individual particles are removed from the
+     * underlying ParticleHandler object, which means that the returned
+     * indices of all particles on an MPI process typically do not form a
+     * contiguous interval of numbers. Use particle properties for storing
+     * persistent information and checkpointing the actual data.
      */
     types::particle_index
     get_local_index() const;

diff --git a/include/deal.II/particles/particle_handler.h b/include/deal.II/particles/particle_handler.h
index 2fe3ec54a36e3be4265ad6ec8045acfc7f047a60..8f19a6fbc18a46d368257ac5929f3c4cbcb344ca 100644 (file)
--- a/include/deal.II/particles/particle_handler.h
+++ b/include/deal.II/particles/particle_handler.h
@@ -661,12 +661,17 @@ namespace Particles
     n_properties_per_particle() const;
 
     /**
-     * Return the maximal local index (in MPI-local index space) returned by
-     * ParticleAccessor::get_local_index(). More precisely, the returned value
-     * is one larger than the largest index that will be returned, which makes
-     * this value useful for resizing vectors. This number can be larger than
-     * locally_owned_particle_ids().n_elements(), because local indices can
-     * contain gaps in the range 0 to get_max_local_particle_index().
+     * Return one past the largest local index (in MPI-local index space)
+     * returned by ParticleAccessor::get_local_index(). This number can be
+     * larger than locally_owned_particle_ids().n_elements(), because local
+     * indices are not necessarily forming a contiguous range and can contain
+     * gaps in the range 0 to get_max_local_particle_index(). As a
+     * consequence, the number is not updated upon calls to remove_particle()
+     * or similar functions, and refreshed only as new particles get added or
+     * in sort_particles_into_subdomains_and_cells().
+     *
+     * This function is appropriate for resizing vectors working with
+     * ParticleAccessor::get_local_index().
      */
     types::particle_index
     get_max_local_particle_index() const;