Index: trunk/MagicSoft/Mars/mtools/MTFillMatrix.cc
===================================================================
--- trunk/MagicSoft/Mars/mtools/MTFillMatrix.cc	(revision 2690)
+++ trunk/MagicSoft/Mars/mtools/MTFillMatrix.cc	(revision 2692)
@@ -25,5 +25,51 @@
 /////////////////////////////////////////////////////////////////////////////
 //
-//   MTFillMatrix
+// MTFillMatrix
+//
+// Use this tool to fill eg trainings and test-matrices, while the matrix
+// to be filled can be a real matrix (MHMatrix) or a file (MWriteRootFile)
+// or both.
+//
+// First create a reference histogram (MH3). For more details see
+// MFEventSelector2 which is used to select events according to the
+// reference histogram.
+//
+//
+// Here is an example of how to choose 1000 events somehow distributed in
+// size from a file.
+// -----------------------------------------------------------------------
+//
+// MH3 ref("MHillas.fSize");          // choose a predefined size distribution
+// // Now setup the distribution
+//
+// MHMatrix matrix1;                   // create matrix to fill
+// matrix.AddColumn("MHillas.fWidth"); // setup columns of your matrix
+//
+// MReadMarsFile read("myfile.root");  // Setup your 'reader'
+// read.DisableAutoScheme();           // make sure everything is read
+//
+// MTFillMatrix fill(ref);             // setup MTFillMatrix
+// fill.SetNumDestEvents1(1000);       // setup number of events to select
+// fill.SetDestMatrix1(&matrix1);      // setup destination matrix
+// if (!fill.Process())                // check if everything worked
+//    return;
+// fill.WriteMatrix1("myoutput.root"); // write matrix to file
+//
+//
+// To get two matrices instead of one (splitted randomly) you can add
+// the following before calling Process():
+// ------------------------------------------------------------------------
+//
+// MHMatrix matrix2;
+// fill.SetNumDestEvents2(500);        // setup number of events to select
+// fill.SetDestMatrix2(&matrix2);      // setup destination matrix
+// [...]
+// fill.WriteMatrix2("myoutput2.root");
+//
+//
+// To write both matrices into a single file use:
+// ----------------------------------------------
+//
+// fill.WriteMatrices("myfile.root");
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -52,4 +98,10 @@
 using namespace std;
 
+// --------------------------------------------------------------------------
+//
+// Print Size and contained columns.
+// Check whether the number of generated events is compatible with
+// the number of requested events.
+//
 Bool_t MTFillMatrix::CheckResult(MHMatrix *m, Int_t num) const
 {
@@ -70,4 +122,9 @@
 }
 
+// --------------------------------------------------------------------------
+//
+// Write the given MHMatrix with its name as default name to a
+// file fname.
+//
 Bool_t MTFillMatrix::WriteMatrix(MHMatrix *m, const TString &fname, Int_t i) const
 {
@@ -83,4 +140,10 @@
 }
 
+// --------------------------------------------------------------------------
+//
+// Constructor. Takes an MH3 as argument. This MH3 is the reference
+// distribution to fill the matrix. More information can be found
+// at MFEventSelector2 which is used to select the events.
+//
 MTFillMatrix::MTFillMatrix(const MH3 &ref)
 : fReference(ref), fReader(0), fDestMatrix1(0),
@@ -92,4 +155,8 @@
 }
 
+// --------------------------------------------------------------------------
+//
+// Fill the matrix (FIXME: Flow diagram missing)
+//
 Bool_t MTFillMatrix::Process()
 {
@@ -186,6 +253,8 @@
     }
 
+    // Print execution statistics of the tasklist
     tlist.PrintStatistics();
 
+    // Check the result of filling...
     CheckResult(fDestMatrix1, fNumDestEvents1);
     CheckResult(fDestMatrix2, fNumDestEvents2);
@@ -195,4 +264,9 @@
 }
 
+// --------------------------------------------------------------------------
+//
+// Write both matrices to a file. Return kFALSE if writing one of them
+// failed or both have the same name.
+//
 Bool_t MTFillMatrix::WriteMatrices(const TString &fname) const
 {