From 80e1c7e555d615b89b3e54386cc13c88b0b4ddf1 Mon Sep 17 00:00:00 2001
From: "OPTIMUS-PRIME\\craig" <craig@craigoates.net>
Date: Mon, 1 Oct 2018 18:26:48 +0100
Subject: [PATCH] add XML comments to public facing library code.

---
 DeathSocket/Domain.fs        | 29 +++++++++++++++--------------
 DeathSocket/GridPainter.fs   | 36 +++++++++++++++++++++++++++++++++---
 DeathSocketCLI/Validation.fs |  3 +--
 TestCentre/LibraryTests.fs   |  4 ++--
 4 files changed, 51 insertions(+), 21 deletions(-)

diff --git a/DeathSocket/Domain.fs b/DeathSocket/Domain.fs
index 04be768..34cc817 100644
--- a/DeathSocket/Domain.fs
+++ b/DeathSocket/Domain.fs
@@ -1,23 +1,24 @@
 namespace DeathSocket
 
+    /// The domain types used by Death Socket.
     [<AutoOpen>]
     module Domain =
 
         open System.Drawing
-        open System.Drawing.Imaging
 
+        /// <summary>
+        /// The specification used by Death Socket when adding a grid to an image.
+        /// </summary>
         type ImageSpec =
-            { originalPath: string;
-              savePath: string;
-              colour: Brush; 
-              penWidth: float32 
-              rows: int;
-              columns: int }
-
-        type StreamSpec =
-            { imagePath: string;
-              format: ImageFormat;
-              colour: Brush; 
-              penWidth: float32 
-              rows: int;
+            { /// The original path of the image which the grid is being added to.
+              originalPath: string
+              /// The location of the new gridded image.
+              savePath: string
+              /// The (System.Drawing) brush used to draw the grid. This determines the colour.
+              colour: Brush
+              /// The thickness of the line on the grid.
+              penWidth: float32
+              /// The number of rows the grid will have.
+              rows: int
+              ///The number of columns the grid will have.
               columns: int }
\ No newline at end of file
diff --git a/DeathSocket/GridPainter.fs b/DeathSocket/GridPainter.fs
index 0dbe187..5ff908b 100644
--- a/DeathSocket/GridPainter.fs
+++ b/DeathSocket/GridPainter.fs
@@ -2,12 +2,30 @@ namespace DeathSocket
 
     open System.IO
 
+    /// Provides functions which help draw gridded overlays onto images.
     module GridPainter =
 
         open Validation
         open ImageServices
 
-        // Needs XML comments.
+        /// <summary>
+        /// Uses the information included in spec and creates a gridded image.
+        /// It then asynchronously saves it.
+        /// Please stick to .bmp, .jpg or .png files.
+        /// The others (image) file types have not been tested.
+        /// </summary>
+        /// <param name="spec">
+        /// The specification used to generate the new gridded image
+        /// </param>
+        /// <exeption cref="System.IO.FileNotFoundException">
+        /// If the file the grid is being applied to cannot be found,
+        /// a FileNotFoundException will be thrown.
+        /// </exception>
+        /// <remarks
+        /// Make sure the image, which is having the overlay added to it,
+        /// is not in use or needed by another program/process.
+        /// This is because it is locked whilst in this function.
+        /// </remarks>
         let applyGridAsync spec =
             async {
                 try
@@ -18,10 +36,22 @@ namespace DeathSocket
                         printfn "File could not be found at %s" ex.Message
             }
 
-        // Needs XML comments.
+        /// <summary>
+        /// Determines the (Pen) points needed to draw the appropriate number of horizontal lines (I.E. rows). 
+        /// Each item in the array includes a start and end co-ordinate (point) for each line.
+        /// </summary>
+        /// <param name="width">The width of the image.</param>
+        /// <param name="height">The height of the image.</param>
+        /// <param name="rows">The number of rows the grid should have.</param>
         let determineHorizontalLines width height rows =
             createHorizontalLines width height rows
 
-        // Needs XML comments.
+        /// <summary>
+        /// Determines the (Pen) points needed to draw the appropriate number of vertical lines (I.E. columns).
+        /// Each item in the array includes a start and end co-ordinate (point) for each line.
+        /// </summary>
+        /// <param name="width">The width of the image.</param>
+        /// <param name="height">The height of the image.</param>
+        /// <param name="columns">The number of columns the grid should have.</param>
         let determineVerticalLines width height columns =
             createVerticalLines width height columns
\ No newline at end of file
diff --git a/DeathSocketCLI/Validation.fs b/DeathSocketCLI/Validation.fs
index c798351..e4cd715 100644
--- a/DeathSocketCLI/Validation.fs
+++ b/DeathSocketCLI/Validation.fs
@@ -58,5 +58,4 @@
               rows = 10
               columns = 10 }
         stream.Dispose ()
-        image.Dispose ()
-        spec
\ No newline at end of file
+        image.Dispose ()
\ No newline at end of file
diff --git a/TestCentre/LibraryTests.fs b/TestCentre/LibraryTests.fs
index 8395d4e..4d15747 100644
--- a/TestCentre/LibraryTests.fs
+++ b/TestCentre/LibraryTests.fs
@@ -128,9 +128,9 @@
         [<Fact>]
         let ``Divide By Zero Exception is thrown when 0 rows is used when determining horizontal lines`` () =
             let result () = GridPainter.determineHorizontalLines 100 100 0
-            Assert.Throws<DivideByZeroException>(fun () -> result() |> ignore)
+            Assert.Throws<DivideByZeroException>(fun () -> result () |> ignore)
 
         [<Fact>]
         let ``Divide By Zero Exception is thrown when 0 columns is used when determining vertical lines`` () =
             let result () = GridPainter.determineVerticalLines 100 100 0
-            Assert.Throws<DivideByZeroException>(fun () -> result() |> ignore)
\ No newline at end of file
+            Assert.Throws<DivideByZeroException>(fun () -> result () |> ignore)
\ No newline at end of file