[Doc] Reverse-engineer variablesizecommunicationtest

That test is a bit difficult to understand unless you know what it tries to
do, which is a problem if that is exactly what you're trying to figure out.
Here are my notes from trying that.

dune/common/parallel/test/variablesizecommunicatortest.cc

@@ -10,6 +10,9 @@
 #include <dune/common/parallel/variablesizecommunicator.hh>
 #include <dune/common/unused.hh>
 
+// For each communicated index, send convert the index to a `double` and send
+// it three times on the sending side.  On the receiving side, simply print
+// the received data.
 struct MyDataHandle
 {
     MyDataHandle(int r)
@@ -52,6 +55,10 @@ struct MyDataHandle
     }
 };
 
+// On the sending side, for each index to send, send bewteen 0 and 4 numbers
+// (precisely: `index % 5` numbers).  The first number is the index converted
+// to `double`, incrementing by one for each consecutive number.  On the
+// receiving side just print the received numbers.
 struct VarDataHandle
 {
     VarDataHandle(int r)
@@ -99,6 +106,9 @@ int main(int argc, char** argv)
     MPI_Comm_size(MPI_COMM_WORLD, &procs);
     if(procs==1)
     {
+        // Invent a consecutive index set with 11 indices [0, 10].  Set every
+        // even index to communicate with ourself.  Then use the data handles
+        // defined at the top of this file to do some test communications.
         typedef Dune::VariableSizeCommunicator<>::InterfaceMap Interface;
         Dune::InterfaceInformation send, recv;
         send.reserve(6);
@@ -129,11 +139,22 @@ int main(int argc, char** argv)
         // and we check for deadlocks.
         if(procs>2)
             --procs;
-        int N=100000;
+
+        // Partition a consecutive set of indices among all active ranks
+        // (where the final rank possibly excluded above is considered
+        // inactive).  Set up interfaces so each rank communicates with its
+        // predecessors at the two indices next to the common partition
+        // boundary, and likewise for the successor.  Then use the data
+        // handles defined at the top of this file to do some test
+        // communications.
+        int N=100000; // number of indices
         int num_per_proc=N/procs;
+        // start is our first index, end is one-past our last index.
         int start, end;
         if(rank<N%procs)
         {
+            // if the #active ranks does not divide #indices, lower ranks get
+            // an additional index in their range
             start=rank*(num_per_proc+1);
             end=(rank+1)*(num_per_proc+1);
         }
@@ -142,12 +163,15 @@ int main(int argc, char** argv)
             start=(N%procs)+rank*(num_per_proc);
             end=start+num_per_proc;
         }
+        // sanity check
         if(rank==procs-1)
             assert(N==end);
         typedef Dune::VariableSizeCommunicator<>::InterfaceMap Interface;
         Interface inf;
         if(rank && rank<procs) // rank==procs might hold and produce a deadlock otherwise!
         {
+            // left interface: communicate our first index and our
+            // predecessor's last index with our predecessor
             Dune::InterfaceInformation send, recv;
             send.reserve(2);
             recv.reserve(2);
@@ -159,7 +183,8 @@ int main(int argc, char** argv)
         }
         if(rank<procs-1)
         {
-
+            // right interface: communicate our last index and our successor's
+            // first index with our successor
             Dune::InterfaceInformation send, recv;
             send.reserve(2);
             recv.reserve(2);
@@ -169,6 +194,7 @@ int main(int argc, char** argv)
             recv.add(end);
             inf[rank+1]=std::make_pair(send, recv);
         }
+        // report inactive rank
         if(rank==procs)
             std::cout<<" rank "<<rank<<" has empty interface "<<inf.size()<<std::endl;
 

dune/common/parallel/variablesizecommunicator.hh

@@ -287,7 +287,7 @@ class VariableSizeCommunicator
 {
 public:
   /**
-     * @brief The type of the map form process number to InterfaceInformation for
+     * @brief The type of the map from process number to InterfaceInformation for
      * sending and receiving to and from it.
      */
   typedef std::map<int,std::pair<InterfaceInformation,InterfaceInformation>,