Suppressing some warnings and adding some explanatory comments

1. declaring variables that can be const, const
2. declaring actual_clear (non-virtual clear) implementations in
   Matrix and SquareMatrix (to avoid warnings about virtual
   functions getting called in destructors!)
3. Running_DecentTree.md now mentions the -num parameter (it didn't!)
4. Detailed a few more missing examples in Command_Line_Examples.md

Author: James Barbetti

clustertree.h

@@ -281,7 +281,7 @@ template <class T> class ClusterTree: public std::vector<Cluster<T>>
             //For each (non-leaf) cluster...
             //1. calculate distances to all the 
             //   leaves, for each contributing cluster.
-            Cluster<T>& node = at(h);
+            const Cluster<T>& node = at(h);
             std::vector<LeafDistanceVector> subtrees;
             for (const Link<T>& link : node.links ) {
                 LeafDistanceVector ldv;

decenttree.cpp

@@ -227,7 +227,7 @@ bool writeMSAOutputFile(const Sequences& sequences, const std::string& msaPath)
         }
         success = true;
     }
-    catch (std::ios::failure& f) {
+    catch (const std::ios::failure& f) {
         std::cerr << "I/O error trying to write"
             << " MSA format file: " << msaPath << std::endl;
     }

distancematrix.h

@@ -93,14 +93,17 @@ template <class T=double> class Matrix
     /**
      * @brief Release any allocated memory
      */
-    virtual void clear() {
+    void actual_clear() {
         delete [] data;
         delete [] rows;
         data         = nullptr;
         rows         = nullptr;
         row_count    = 0;
         column_count = 0;
     }
+    virtual void clear() {
+        actual_clear();
+    }
     /**
      * @brief  get a const reference to the pointer to the const
      *         first element in the matrix, in the (r)th row.
@@ -443,13 +446,16 @@ template <class T=double> class SquareMatrix: public Matrix<T>
         assign(rhs);
     }
     virtual ~SquareMatrix() {
-        clear();
+        actual_clear();
     }
-    virtual void clear() override {
-        super::clear();
+    void actual_clear() {
         delete [] rowTotals;
         rowTotals = nullptr;
     }
+    virtual void clear() override {
+        super::clear();
+        actual_clear();
+    }
     SquareMatrix& operator=(const SquareMatrix& rhs) {
         assign(rhs);
         return *this;
@@ -568,7 +574,10 @@ template <class F=std::stringstream, class M> intptr_t loadPartialRowFromLine
 }
 
 /**
- * @brief 
+ * @brief  if it hasn't been determined already, determine - from a single matrix
+ *         row that has just been read in, whether the matrix representation 
+ *         in the file being read is square, upper triangle, or lower triangle.
+ * 
  * @tparam M the matrix type
  * @tparam P the type used to report progress (expected to implement
  *           hide() and show() members).

doco/Command_Line_Examples.md

@@ -57,7 +57,8 @@ Todo: Provide example command-lines for:
 <ul>
 <li>[todo: -msa-out]</li>
 <li>[todo: -strip-name] + [todo: -name-replace]</li>
-<li>[todo: -aln-out] Phylip Interleaved format</li>
+<li>[todo: -truncate-name-at] (truncation of long names)</li>
+<li>[todo: -num] (replacing names with numbered names, of the form A_i_ where _i_ is a number between 1 and _n_, the number of taxa)</li>
 </ul>
 
 |Command Line|Explanation|
@@ -68,6 +69,13 @@ Todo: Provide example command-lines for:
 
 <h2>Distance Matrices as outputs</h2>
 
+Todo:
+<ul>
+<li>-no-matrix (if a distance matrix file is being generated, and a phylogenetic tree is not being inferred, -t NONE,
+    it isn't strictly necessary to create an in-memory distance matrix, and this option tells decenttree to save memory
+    by NOT allocating or using one). 
+</ul>
+
 |Command Line|Explanation|
 |------------|-----------|
 |decenttree -phylip ../example/example.phy -no-banner -dist example.dist -out-format upper -t NONE -no-out | Using the default distance matrix algorithm, infer a distance matrix, and write the distance matrix (in upper-triangle Phylip format) to the file, example.dist. -t NONE says *not* to use a phylogenetic inference algorithm.  If no out-format parameter is provided the default is square. |

doco/Running_DecentTree.md

@@ -14,12 +14,13 @@
 | -not-dna    |                        | with -fasta, indicates input is (not) DNA     |
 | -alphabet   | list of characters     | with -fasta, recognized nucleotide characters |
 | -unknown    | list of characters     | with -fasta, characters that indicate unknown |
-| -strip-name   | list of characters | Characters to strip from taxon names (case sensitive) |
-| -name-replace | list of characters | Characters to replace the stripped characters with |
+| -strip-name   | list of characters   | Characters to strip from taxon names (case sensitive) |
+| -name-replace | list of characters   | Characters to replace the stripped characters with |
 | -truncate-name-at | list of characters | Truncate taxon name on one of these characters |
+| -num        |                          | Replace all taxon names with numbered names of the form A_i_ (_i_ is taxon number, starting at 1) | 
 | -uncorrected | | with -fasta, do not apply Jukes-Cantor distance correction to calculated distances |
-| -filter     | | with -fasta, Filter sequences that have zero distance |
-| -no-matrix  |  | with -fasta, save memory by *not* constructing the input matrix in memory  |
+| -filter     |  | with -fasta, Filter sequences that have zero distances |
+| -no-matrix  |  | with -fasta, save memory by *not* constructing the input matrix in memory (only has an effect with -t NONE) |
 | -msa-out    | msa output file path             | given -fasta or -phylip, rewrite alignment in msa format |
 | -dist-out   | distance matrix output file path | Use STDOUT to write it to standard output  |
 | -t          | algorithm name                   | Specify the algorithm to use to construct the tree (or none) |

flatmatrix.h

@@ -111,14 +111,20 @@ class FlatMatrix {
                                            const std::string& file_name) const;
 
     /**
-     * @brief 
+     * @brief  write the sequence names, and the distance matrix,
+     *         in one of the Phylip distance matrix formats, to the 
+     *         file with the specified file stream.
      * 
      * @tparam S the stream type 
      * @tparam P the progress display class
      * @param  format    the format ("square", "upper", or "lower")
      * @param  precision the precision (number of digits to use after decimal point)
      * @param  out       the output stream
      * @param  progress  pointer to the class instance used to report progress
+     * 
+     * @note   S is a template parameter because this function is used to
+     *           write a standard file output stream, or to a zipped file stream
+     *           (to std::ofstream or to ogzstream).
      */
     template <class S /*stream type*/, class P /*progress display*/>
     void               writeDistancesToOpenFile(const std::string& format,

nj.h

@@ -526,7 +526,9 @@ template <class T=NJFloat> class BIONJMatrix : public NJMatrix<T> {
 
 #if USE_VECTORCLASS_LIBRARY
 /**
- * @brief 
+ * @brief  Vectorizing shim for distance matrix algorithm classes
+ *         (Vectorized<X> yields a vectorized subclass of X, 
+ *         if X meets the requirements, listed below).
  * 
  * @tparam T the distance type
  * @tparam SUPER the superclass (in practice, NJMatrix<T>, 

starttree.h

@@ -180,8 +180,9 @@ namespace StartTree
         virtual bool setAppendFile(bool appendIt) = 0; //returns true if supported
 
         /**
-         * @brief 
-         * 
+         * @brief tell the distance matrix algorithm to avoid writing anything
+         *        to standard output (it may still write to standard error if 
+         *        something goes wrong).
          */
         virtual void beSilent() = 0;
 

utils/argument.h

@@ -18,7 +18,10 @@ class Argument {
     explicit Argument(const char* arg_name);
     virtual ~Argument() = default;
     /**
-     * @brief 
+     * @brief          Accept a recognized argument (found in the command-line)
+     *                 (if the argument takes a parameter - or parameters - 
+     *                 this entails doing something with it; parsing it, possibly
+     *                 validating it.  The details vary between subclasses).
      * @param arg      The argument that matched the name
      * @param nextArg  The next argument
      * @param argv     The command-line argument array

utils/hammingdistance.h

@@ -239,7 +239,10 @@ inline uint64_t countBitsSetInEither
 
 //W is the number of bytes in a CV (or CBV)
 /**
- * @brief 
+ * @brief  Determine hamming distance between two sequences 
+ *         (using the specified vector types, supplied via 
+ *         the template parameters).
+ * 
  * @tparam DV  - distance vector type  (of W/8 uint64_t)
  * @tparam CV  - character vector type (of W characters)
  * @tparam CBV - boolean vector type   (same rank as CV)

utils/my_assert.h

@@ -36,7 +36,7 @@ inline void _my_assert(const char* expression, const char *func, const char* fil
     abort();
 }
 
-inline void _my_assert(const std::string str_expression, const char *func, const char* file, int line) {
+inline void _my_assert(const std::string &str_expression, const char *func, const char* file, int line) {
     _my_assert(str_expression.c_str(), func, file, line);
 }