add documentation

add descriptions of what the classes and methods do.

src/AnalysisPrograms/ContentDescription.cs

@@ -22,6 +22,14 @@ namespace AnalysisPrograms
     using log4net;
     using TowseyLibrary;
 
+    /// <summary>
+    /// This class is derived from AbstractStrongAnalyser.
+    /// It is equivalent to AnalyseLongRecording.cs or a SpeciesRecognizer.cs.
+    /// To call this class, the first argument on the commandline must be 'audio2csv'.
+    /// Given a one-minute recording segment, the ContentDescription.Analyze() method calls AudioAnalysisTools.Indices.IndexCalculateSixOnly.Analysis().
+    /// This calculates six spectral indices, ACI, ENT, EVN, BGN, PMN, OSC. This set of 6x256 acoustic features is used for content description.
+    /// The content description methods are called from ContentDescription.SummariseResults() method.
+    /// </summary>
     public class ContentDescription : AbstractStrongAnalyser
     {
         public const string AnalysisName = "ContentDescription";

src/AudioAnalysisTools/ContentDescriptionTools/ContentSignatures.cs

@@ -10,6 +10,12 @@ namespace AudioAnalysisTools.ContentDescriptionTools
     using Acoustics.Shared;
     using TowseyLibrary;
 
+    /// <summary>
+    /// This class contains methods which use functional templates to scan one or multiple files to obtain a content description.
+    /// For consistency between recordings many parameters such as sample rate, frame size etc, must be declared as constants.
+    /// In addition, the absolute values in the template description dictionary must be normalised using the fixed set of normalisation bounds in IndexValueBounds.
+    /// Note that each functional template uses one of a small number of algorithms to calculate a similarity value.
+    /// </summary>
     public class ContentSignatures
     {
         // All the code base for content description assumes a sampling rate of 22050 (i.e. a Nyquist = 11025) and frame size = 512 (i.e. 256 frequency bins).
@@ -33,9 +39,16 @@ public class ContentSignatures
             ["PMN"] = new[] { 0.0, 5.5 },
         };
 
+        /// <summary>
+        /// Gets an array of six spectral indices that are calculated.
+        /// </summary>
         public static string[] IndexNames { get; } = { "ACI", "ENT", "EVN", "BGN", "PMN", "OSC" };
 
-        // Following array is used to remove unwanted selectors.
+        /// <summary>
+        /// Gets an array containing names of spectral indices that are not wanted. They are used to remove unwanted selectors.
+        /// This is a temporary arrangement to utilize existing code.
+        /// TODO Eventually separate out template results so do not have to use the AnalysisResult2 class.
+        /// </summary>
         public static string[] UnusedIndexNames { get; } = { "CVR", "DIF", "RHZ", "RVT", "RPS", "RNG", "R3D", "SPT", "SUM" };
 
         /// <summary>

src/AudioAnalysisTools/ContentDescriptionTools/TemplateManifest.cs

@@ -11,23 +11,31 @@ namespace AudioAnalysisTools.ContentDescriptionTools
 
     /// <summary>
     /// Templates are initially defined manually in a yml file. Each template in a yml file is called a "manifest".
-    /// The array of manifests in a yml file is used to calculate an array of "working templates" in a json file.
+    /// The array of manifests in a yml file is used to calculate an array of "functional templates" in a json file.
     /// The json file is generated automatically from the information provided in the manifests.yml file.
-    /// A  template manifest contains the "provenance" of the template (i.e. the detail of the recordings and locaitons of recording files used to make the working template.
+    /// A  template manifest contains the "provenance" of the template (i.e. details of the recordings, source locations etc used to make the functional template.
     /// It also contains the information required to calculate the template definition.
-    /// The core of a working template is its definition which stored as a dictionary of spectral indices.
-    /// The working template also contains information required to scan new recordings with the demplate definition.
+    /// The core of a functional template is its definition, which is stored as a dictionary of spectral indices.
+    /// The functional template also contains information required to scan new recordings with the template definition.
     ///
     /// Each template manifest in a yml file contains an EditStatus field which describes what to with the manifest.
     /// There are there options as described below.
     /// </summary>
     public enum EditStatus
     {
-        Edit,   // This option edits an existing working template in the json file. The template definition is (re)calculated.
-        Copy,   // This option keeps an existing working template unchanged except for its template Id. Template Ids are assigned in order they appear in the yml file.
-        Ignore, // This option keeps an existing working template unchanged except changes its UseStatus boolean field to FALSE.
+        Edit,   // This option edits an existing functional template in the json file. The template definition is (re)calculated.
+        Copy,   // This option keeps an existing functional template unchanged except for its template Id. Template Ids are assigned in order they appear in the yml file.
+        Ignore, // This option keeps an existing functional template unchanged except changes its UseStatus boolean field to FALSE.
     }
 
+    /// <summary>
+    /// This is base class for both template manifests and functional templates.
+    /// Most of the fields and properties are common to both manifests and functional templates.
+    /// Manifests contain the template provenance. This does not appear in the functional template because provenance includes path data.
+    /// TODO Set up inheritance from base class so that there is separate class for manifests and functional templates.
+    ///
+    /// This class also contains methods to create new or edit existing functional templates based on info in the manifests.
+    /// </summary>
     public class TemplateManifest
     {
         public static void CreateNewFileOfTemplateDefinitions(FileInfo manifestFile, FileInfo templateDefinitionsFile)
@@ -60,7 +68,7 @@ public static void CreateNewFileOfTemplateDefinitions(FileInfo manifestFile, Fil
 
                 if (manifest.EditStatus == EditStatus.Edit)
                 {
-                    // This option edits an existing working template in the json file. The template definition is (re)calculated.
+                    // This option edits an existing functional template in the json file. The template definition is (re)calculated.
                     var newTemplate = CreateNewTemplateFromManifest(manifest);
                     newTemplate.TemplateId = i;
                     newTemplate.Template = CreateTemplateDefinition(manifest);
@@ -71,7 +79,7 @@ public static void CreateNewFileOfTemplateDefinitions(FileInfo manifestFile, Fil
 
                 if (manifest.EditStatus == EditStatus.Copy)
                 {
-                    // This option keeps an existing working template unchanged except for its template Id.
+                    // This option keeps an existing functional template unchanged except for its template Id.
                     // Template ids are assigned in order they appear in the yml file.
                     var existingTemplate = dictionaryOfCurrentTemplates[name];
                     existingTemplate.TemplateId = i;
@@ -83,7 +91,7 @@ public static void CreateNewFileOfTemplateDefinitions(FileInfo manifestFile, Fil
 
                 if (manifest.EditStatus == EditStatus.Ignore)
                 {
-                    // This option keeps an existing working template unchanged except changes its UseStatus boolean field to FALSE.
+                    // This option keeps an existing functional template unchanged except changes its UseStatus boolean field to FALSE.
                     var existingTemplate = dictionaryOfCurrentTemplates[name];
                     existingTemplate.TemplateId = i;
                     existingTemplate.Provenance = null;