Added XML comments to the rest of the functions in ProductServices.fs

WetPancake/ProductServices.fs

@@ -13,16 +13,24 @@ module  Pancake =
     open System.IO
 
     (* ===============================================================================================================
-    YOU ARE UP TO HERE - WEDNESDAY 25 TH JULY 2018
+    YOU ARE UP TO HERE - Friday 27th TH JULY 2018
     [] DO NOT FORGET TO WRITE THE COMMAND-METHODS IN CONSOLECOMMANDS.CS
-    [] XML COMMENTS IN THIS FILE
     =============================================================================================================== *)
 
     /// <summary>
-    /// 
+    /// Checks to see if the string matches the desired sentence count and removes any over that limit.
+    /// This function is ascynchronous.
     /// </summary>
-    /// <param name="noOfSentences"></param>
-    /// <param name="text"></param>
+    /// <param name="noOfSentences">
+    /// The number of sentences the cleaned string should have.
+    /// </param>
+    /// <param name="text">
+    /// The string to clean.
+    /// </param>
+    /// <remarks>
+    /// This function's aim is to trim or remove excess sentences.
+    /// If the string has less sentences than the number requested, it will not change.
+    /// </remarks> 
     let CleanResultAsync noOfSentences text =
         async {
             let cleanText =
@@ -92,7 +100,8 @@ module  Pancake =
 
     /// <summary>
     /// An asynchronous function which generates text. 
-    /// It generates the text by using the (.txt) file passed in by the caller (as the reference) and the parameters specified by the caller.
+    /// It generates the text by using the (.txt) file passed in by the caller (as the reference)
+    /// It, also, uses the parameters specified by the caller.
     /// </summary>
     /// <param name="gibberishLevel">
     /// Specifies how coherent the generated text is.
@@ -164,10 +173,32 @@ module  Pancake =
         }
 
     /// <summary>
-    /// 
+    /// An asynchronous function which generates random text.
+    /// It uses the built-in template (.txt) files as a reference and the parameters specified by the user.
+    /// It, also, goes through a "cleaning" process which removes any excess sentences.
     /// </summary>
-    /// <param name="gibberishLevel"></param>
-    /// <param name="sentences"></param>
+    /// <param name="gibberishLevel">
+    /// Specifies how coherent the generated text is.
+    /// Min. value = 2. Max. value = 20.
+    /// The lower the value the more gibberish it will produce.</param>
+    /// <param name="sentences">
+    /// Specifies the number of sentences to generate.
+    /// </param>
+    /// <returns>
+    /// A string of randomly generated text.
+    /// </returns>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when the "gibberishLevel" is not between 2 and 20.
+    /// </exception>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when the "sentences" count is less than 1.
+    /// </exception>
+    /// <remarks>
+    /// This function produces more accurate results than the equivalent RequestTextAsync.
+    /// Although, it does take loner to complete.
+    /// If you can tolerate the odd extra sentences and prefer speed, use RequestextAsync.
+    /// If not, use this.
+    /// </remarks> 
     let RequestCleanTextAsync (gibberishLevel: int) (sentences: int) =
         async {
             let! text = RequestTextAsync gibberishLevel sentences
@@ -176,11 +207,49 @@ module  Pancake =
         }
 
     /// <summary>
-    /// 
+    /// An asynchronous function which generates text. 
+    /// It generates the text by using the (.txt) file passed in by the caller (as the reference)
+    /// It, also, uses the parameters specified by the caller.
+    /// On top of that, it goes through a "cleaning" process which removes any excess sentences.
     /// </summary>
-    /// <param name="gibberishLevel"></param>
-    /// <param name="sentences"></param>
-    /// <param name="filePath"></param>
+    /// <param name="gibberishLevel">
+    /// Specifies how coherent the generated text is.
+    /// Min. value = 2. Max. value = 20.
+    /// The lower the value the more gibberish it will produce.
+    /// </param>
+    /// <param name="sentences">
+    /// Specifies the number of sentences to generate.
+    /// </param>
+    /// <param name="filePath">
+    /// The path of the (.txt) file the function will use as the reference text. 
+    /// </param>
+    /// <returns>
+    /// A string of randomly generated text.
+    /// </returns>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when the "gibberishLevel" is not between 2 and 20.
+    /// </exception>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when the "sentences" count is less than 1.
+    /// </exception>
+    /// <exception cref="System.FileNotFoundException">
+    /// Thrown when the (.txt) file cannot be found.
+    /// </exception>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when the specified file is not a plain-text (.txt) file.
+    /// </exception>
+    /// <remarks>
+    /// The higher the “gibberishLevel” and the “sentences” count is the longer it will take to complete the task.
+    /// This, also, applies to the (.txt) file passed into the function.
+    /// The bigger it is, the longer it will take to read.
+    /// Try to make the most of the asynchronous nature of the function as possible.
+    /// Also, the function does not know what is in the (.txt) file until it reads it.
+    /// Defensive coding should be applied here.
+    /// This function produces more accurate results than it RequestTextFromFileAsync equivalent.
+    /// Although, it does take loner to complete.
+    /// If you can tolerate the odd extra sentences and prefer speed, use RequestextAsync.
+    /// If not, use this.
+    /// </remarks>
     let RequestCleanTextFromFileAsync (gibberishLevel: int) (sentences: int) (filePath: string) =
         async {
             let! text = RequestTextFromFileAsync gibberishLevel sentences filePath