Improve documentation. Do not output the number of cells any more (only the number...

git-svn-id: https://svn.dealii.org/trunk@33054 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/examples/step-3/doc/results.dox b/deal.II/examples/step-3/doc/results.dox
index 50012fae175b9a4a2a25c05e0ccd67c76ef6a661..72d17c2d2c8496b897bf0567448a11c4a375b356 100644 (file)
--- a/deal.II/examples/step-3/doc/results.dox
+++ b/deal.II/examples/step-3/doc/results.dox
@@ -3,7 +3,6 @@
 The output of the program looks as follows:
 @code
 Number of active cells: 1024
-Total number of cells: 1365
 Number of degrees of freedom: 1089
 DEAL:cg::Starting value 0.121094
 DEAL:cg::Convergence step 48 value 5.33692e-13

diff --git a/deal.II/examples/step-3/step-3.cc b/deal.II/examples/step-3/step-3.cc
index 1f861e58d3044de484b50b7e32ff561dd5530cb5..eab972bc8789571a2c8b3ff8fd050db4783b1b38 100644 (file)
--- a/deal.II/examples/step-3/step-3.cc
+++ b/deal.II/examples/step-3/step-3.cc
@@ -153,32 +153,40 @@ Step3::Step3 ()
 
 // Now, the first thing we've got to do is to generate the triangulation on
 // which we would like to do our computation and number each vertex with a
-// degree of freedom. We have seen this in the previous examples before.
+// degree of freedom. We have seen these two steps in step-1 and step-2
+// before, respectively.
+//
+// This function does the first part, creating the mesh.
+// We create the grid and refine all cells five times. Since the initial
+// grid (which is the square [-1,1]x[-1,1]) consists of only one cell, the
+// final grid has 32 times 32 cells, for a total of 1024.
+//
+// Unsure that 1024 is the correct number? We can check that by outputting the
+// number of cells using the <code>n_active_cells()</code> function on the
+// triangulation.
 void Step3::make_grid ()
 {
-  // First create the grid and refine all cells five times. Since the initial
-  // grid (which is the square [-1,1]x[-1,1]) consists of only one cell, the
-  // final grid has 32 times 32 cells, for a total of 1024.
   GridGenerator::hyper_cube (triangulation, -1, 1);
   triangulation.refine_global (5);
-  // Unsure that 1024 is the correct number?  Let's see: n_active_cells
-  // returns the number of active cells:
+
   std::cout << "Number of active cells: "
             << triangulation.n_active_cells()
             << std::endl;
-  // Here, by active we mean the cells that aren't refined any further.  We
-  // stress the adjective `active', since there are more cells, namely the
-  // parent cells of the finest cells, their parents, etc, up to the one cell
-  // which made up the initial grid. Of course, on the next coarser level, the
-  // number of cells is one quarter that of the cells on the finest level,
-  // i.e. 256, then 64, 16, 4, and 1. We can get the total number of cells
-  // like this:
-  std::cout << "Total number of cells: "
-            << triangulation.n_cells()
-            << std::endl;
-  // Note the distinction between n_active_cells() and n_cells().
 }
 
+// @note We call the Triangulation::n_active_cells() function, rather than
+// Triangulation::n_cells(). Here, <i>active</i> means the cells that aren't
+// refined any further. We stress the adjective "active" since there are more
+// cells, namely the parent cells of the finest cells, their parents, etc, up
+// to the one cell which made up the initial grid. Of course, on the next
+// coarser level, the number of cells is one quarter that of the cells on the
+// finest level, i.e. 256, then 64, 16, 4, and 1. If you called
+// <code>triangulation.n_cells()</code> instead in the code above, you would
+// consequently get a value of 1365 instead. On the other hand, the number of
+// cells (as opposed to the number of active cells) is not typically of much
+// interest, so there is no good reason to print it.
+
+
 // @sect4{Step3::setup_system}
 
 // Next we enumerate all the degrees of freedom and set up matrix and vector