Added comments: License boiler plate & XMLDoc documentation

Author: delphidabbler

Src/SWAG.UVersion.pas

@@ -1,3 +1,15 @@
+{
+ * This Source Code Form is subject to the terms of the Mozilla Public License,
+ * v. 2.0. If a copy of the MPL was not distributed with this file, You can
+ * obtain one at http://mozilla.org/MPL/2.0/
+ *
+ * Copyright (C) 2020, Peter Johnson (gravatar.com/delphidabbler).
+ *
+ * Provides a class that reads and validates the SWAG collection's version
+ * information from file.
+}
+
+
 unit SWAG.UVersion;
 
 
@@ -14,25 +26,69 @@ interface
 
 
 type
+  ///  <summary>Class that reads and validates the SWAG collection's version
+  ///  information from file.</summary>
   TSWAGVersion = class(TNoPublicConstructObject)
   strict private
     const
+      ///  <summary>First supported SWAG version.</summary>
       LowestSupportedVersion: TVersionNumber = (V1: 1; V2: 0; V3: 0; V4: 0);
+      ///  <summary>Lowest SWAG version that is NOT supported.</summary>
       LowestUnSupportedVersion: TVersionNumber = (V1: 1; V2: 1; V3: 0; V4: 0);
+      ///  <summary>SWAG version file name, without path.</summary>
       SWAGVersionFileName = 'VERSION';
     var
+      ///  <summary>Stores fully specified path to SWAG version file.</summary>
       fSWAGFilePath: TFileName;
+    ///  <summary>Reads and returns the version string from the version file.
+    ///  </summary>
     function ReadVersionStr: string;
+    ///  <summary>Reads, parses and validates version information from file.
+    ///  </summary>
+    ///  <returns>TVersionNumber. Structure containing version information.
+    ///  </returns>
+    ///  <exception>ECorruptSWAGVersion raised if version information in file
+    ///  is corrupt, missing, or if the file is missing.</exception>
+    ///  <exception>EUnsupportedSWAGVersion raised if the version information
+    ///  read represents an unsupported format.</exception>
     function ReadAndValidateVersionFile: TVersionNumber;
   strict protected
+    ///  <summary>Constructor that can only be called from with the class.
+    ///  </summary>
+    ///  <param name="SWAGDir">TFileName [in] Directory where version file
+    ///  should be located.</param>
     constructor InternalCreate(const SWAGDir: TFileName);
   public
+    ///  <summary>Validates the version file. Returns normally if there are no
+    ///  errors or raises an exception if an error is found.</summary>
+    ///  <param name="SWAGDir">TFileName [in] Directory where version file
+    ///  should be located.</param>
+    ///  <exception>ECorruptSWAGVersion raised if version information in file
+    ///  is corrupt, missing, or if the file is missing.</exception>
+    ///  <exception>EUnsupportedSWAGVersion raised if the version information
+    ///  read represents an unsupported format.</exception>
     class procedure ValidateVersionFile(const SWAGDir: TFileName);
-    class function GetVersion(const SWAGDir: TFileName): TVersionNumber;
+    ///  <summary>Gets SWAG version from file.</summary>
+    ///  <param name="SWAGDir">TFileName [in] Directory where version file
+    ///  should be located.</param>
+    ///  <returns>TVersionNumber. Structure containing version information.
+    ///  </returns>
+    ///  <exception>ECorruptSWAGVersion raised if version information in file
+    ///  is corrupt, missing, or if the file is missing.</exception>
+    ///  <exception>EUnsupportedSWAGVersion raised if the version information
+    ///  read represents an unsupported format.</exception>
+   class function GetVersion(const SWAGDir: TFileName): TVersionNumber;
   end;
 
+  ///  <summary>Base class for exceptions raised in this unit.</summary>
+  ///  <remarks>Exceptions of this type should NOT be raised directly: use
+  ///  sub-classes.</remarks>
   ESWAGVersion = class(ECodeSnip);
+  ///  <summary>Type of exception raised when the SWAG version file is missing
+  ///  or corrupt.</summary>
   ECorruptSWAGVersion = class(ESWAGVersion);
+  ///  <summary>Type of exception raised when the SWAG version is outside the
+  ///  range of supported versions.</summary>
   EUnsupportedSWAGVersion = class(ESWAGVersion);