From ae03c22cfb6bcc2c25f4cb2ba964cc1c8c32f44d Mon Sep 17 00:00:00 2001
From: Rene Gassmoeller <rene.gassmoeller@mailbox.org>
Date: Wed, 14 Aug 2019 18:56:47 -0700
Subject: [PATCH] Extend documentation. Refactor loops.

---
 .../deal.II/particles/particle_generator.h    | 16 +++++++++++++
 source/particles/particle_generator.cc        | 23 +++++++------------
 2 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/include/deal.II/particles/particle_generator.h b/include/deal.II/particles/particle_generator.h
index e4cab73ff9..acec16a738 100644
--- a/include/deal.II/particles/particle_generator.h
+++ b/include/deal.II/particles/particle_generator.h
@@ -35,6 +35,22 @@ namespace Particles
   {
     /**
      * A function that generates particles in every cell at specified @p particle_reference_locations.
+     * The total number of particles that is added to the @p partiche_handler object is
+     * the number of locally owned cells of the @p triangulation times the number of
+     * locations in @p particle_reference_locations. An optional @p mapping argument
+     * can be used to map from @p particle_reference_locations to the real particle locations.
+     *
+     * @param triangulation The triangulation associated with the @p particle_handler.
+     *
+     * @param particle_reference_locations A vector of positions in the unit cell.
+     * Particles will be generated in every cell at these locations.
+     *
+     * @param particle_handler The particle handler that will take ownership
+     *  of the generated particles.
+     *
+     * @param mapping An optional mapping object that is used to map reference
+     * location in the unit cell to the real cells of the triangulation. If no
+     * mapping is provided a MappingQ1 is assumed.
      */
     template <int dim, int spacedim = dim>
     void
diff --git a/source/particles/particle_generator.cc b/source/particles/particle_generator.cc
index de923d07ec..b6378cd399 100644
--- a/source/particles/particle_generator.cc
+++ b/source/particles/particle_generator.cc
@@ -48,27 +48,20 @@ namespace Particles
 
       types::particle_index particle_index = local_start_index;
 
-      typename Triangulation<dim, spacedim>::active_cell_iterator
-        cell = triangulation.begin_active(),
-        endc = triangulation.end();
-
-      for (; cell != endc; cell++)
+      for (const auto &cell : triangulation.active_cell_iterators())
         {
           if (cell->is_locally_owned())
             {
-              for (typename std::vector<Point<dim>>::const_iterator
-                     itr_particles_in_unit_cell =
-                       particle_reference_locations.begin();
-                   itr_particles_in_unit_cell !=
-                   particle_reference_locations.end();
-                   itr_particles_in_unit_cell++)
+              for (const auto &reference_location :
+                   particle_reference_locations)
                 {
                   const Point<spacedim> position_real =
-                    mapping.transform_unit_to_real_cell(
-                      cell, *itr_particles_in_unit_cell);
+                    mapping.transform_unit_to_real_cell(cell,
+                                                        reference_location);
 
-                  const Particle<dim, spacedim> particle(
-                    position_real, *itr_particles_in_unit_cell, particle_index);
+                  const Particle<dim, spacedim> particle(position_real,
+                                                         reference_location,
+                                                         particle_index);
                   particle_handler.insert_particle(particle, cell);
                   ++particle_index;
                 }
-- 
2.39.5