From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 20 Oct 2020 00:02:12 +0000 (-0600)
Subject: Update documentation of PropertyPool.
X-Git-Tag: v9.3.0-rc1~961^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=be9bc362d592837290ff83db47adae929bab2d79;p=dealii.git

Update documentation of PropertyPool.
---

diff --git a/include/deal.II/particles/property_pool.h b/include/deal.II/particles/property_pool.h
index 4689e191f2..8f34ee5e91 100644
--- a/include/deal.II/particles/property_pool.h
+++ b/include/deal.II/particles/property_pool.h
@@ -25,20 +25,23 @@ DEAL_II_NAMESPACE_OPEN
 namespace Particles
 {
   /**
-   * This class manages a memory space in which particles store their
-   * properties. Because this is dynamic memory and often every particle
-   * needs the same amount, it is more efficient to let this be handled by a
-   * central manager that does not need to allocate/deallocate memory every
-   * time a particle is constructed/destroyed.
-   * The current implementation uses simple new/delete allocation for every
-   * block. Additionally, the current implementation
-   * assumes the same number of properties per particle, but of course the
-   * PropertyType could contain a pointer to dynamically allocated memory
-   * with varying sizes per particle (this memory would not be managed by this
-   * class).
-   * Because PropertyPool only returns handles it could be enhanced internally
-   * (e.g. to allow for varying number of properties per handle) without
-   * affecting its interface.
+   * This class manages a memory space in which all particles associated with
+   * a ParticleHandler store their properties. The rationale for this class is
+   * that because typically every particle stores the same number of
+   * properties, and because algorithms generally traverse over all particles
+   * doing the same operation on all particles' properties, it is more efficient
+   * to let the memory used for properties be handled by a central manager.
+   * Particles then do not store a pointer to a memory area in which they store
+   * their properties, but instead a "handle" that the PropertyPool class then
+   * translates into a pointer to concrete memory.
+   *
+   * All this said, the current implementation only provides this kind of
+   * interface, but still uses simple new/delete allocation for every
+   * set of properties requested by a particle. Additionally, the current
+   * implementation assumes the same number of properties per particle, but of
+   * course the PropertyType could contain a pointer to dynamically allocated
+   * memory with varying sizes per particle (this memory would not be managed by
+   * this class).
    */
   class PropertyPool
   {