From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Tue, 17 Jun 2014 11:23:30 +0000 (+0000)
Subject: Improve documentation. Do not output the number of cells any more (only the number... 
X-Git-Tag: v8.2.0-rc1~384
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=400dd0dd4b30a0c99d304ff3bf0be9f19a99d9ae;p=dealii.git

Improve documentation. Do not output the number of cells any more (only the number of active cells) because it is not often of great interest. Talk about it, though.

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 50012fae17..72d17c2d2c 100644
--- 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 1f861e58d3..eab972bc87 100644
--- 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