Merge pull request #67 from delegateas/tst/xml-docs

docs: Added xml comments to some functions to generate function documentation

Author: thygesteffensen

.github/workflows/build.yml

@@ -44,26 +44,28 @@ jobs:
       - name: Build solution
         run: dotnet build -o build/${{ matrix.dotnet }} -c Release --no-restore -m:1 -f ${{ matrix.dotnet }}
 
-      - name: Cache artifactes
+      - name: Cache build artifacts
         uses: actions/cache@v2
         with:
-          path: build
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-temp
+          path: build/${{ matrix.dotnet }}
+          key: ${{ runner.os }}-build-${{ matrix.dotnet }}
 
   publish:
     runs-on: windows-latest
     name: Generate docs and publish artifacts
     needs: ['build']
     steps:
-      - name: Get cache
+      - name: Get cache - net5.0
         uses: actions/cache@v2
         with:
-          path: build
-          key: ${{ runner.os }}-build-${{ env.cache-name }}-temp
-      
-      - run: dir
+          path: build/net5.0
+          key: ${{ runner.os }}-build-net5.0
 
-      - run: dir build
+      - name: Get cache - netcoreapp3.1
+        uses: actions/cache@v2
+        with:
+          path: build/netcoreapp3.1
+          key: ${{ runner.os }}-build-netcoreapp3.1
 
       - uses: actions/setup-dotnet@v1
         with:
@@ -73,7 +75,7 @@ jobs:
         run: dotnet new tool-manifest && dotnet tool install EAVFW.Extensions.Docs.TransformToMarkdown
 
       - name: Generate docs
-        run: dotnet tool run tomd --input build/netcoreapp3.1/ExpressionEngine.xml --output Documentation.md
+        run: dotnet tool run tomd --input build/net5.0/ExpressionEngine.xml --output Documentation.md
 
       - name: Archive build to artifacts
         uses: actions/upload-artifact@v2.3.1
@@ -82,5 +84,10 @@ jobs:
           path: |
             build/netcoreapp3.1/
             build/net5.0/
-            Documentation.md
           retention-days: 5
+          
+      - name: Archive documentation to artifacts
+        uses: actions/upload-artifact@v2.3.1
+        with:
+          name: Documentation
+          path: Documentation.md

ExpressionEngine/Functions/Implementations/StringFunctions/ConcatFunction.cs

@@ -11,14 +11,30 @@ public ConcatFunction() : base("concat")
         {
         }
 
+        /// <functionName>concat</functionName>
+        /// <summary>
+        /// Combine two or more strings, and return the combined string.
+        /// </summary>
+        /// <definition>
+        /// concat('$lttext1$gt', '$lttext2$gt', ...)
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext1$gt, $lttext2$gt, ..." required="Yes" type="String">At least two strings to combine</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>$lttext1$gt, $lttext2$gt, ...</value>
+        ///     <type>String</type>
+        ///     <description>The string created from the combined input strings. <br/><br/> Note: The length of the result must not exceed 104,857,600 characters.</description>
+        /// </returns>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 2)
             {
                 throw new ArgumentError("Too few arguments");
             }
 
-            return new ValueTask<ValueContainer>(new ValueContainer(parameters.Aggregate("", (current, value) => current + AuxiliaryMethods.VcIsString(value))));
+            return new ValueTask<ValueContainer>(new ValueContainer(parameters.Aggregate("",
+                (current, value) => current + AuxiliaryMethods.VcIsString(value))));
         }
     }
 }

ExpressionEngine/Functions/Implementations/StringFunctions/EndsWithFunction.cs

@@ -10,6 +10,22 @@ public EndsWithFunction() : base("endsWith")
         {
         }
 
+        /// <functionName>endsWith</functionName>
+        /// <summary>
+        /// Check whether a string ends with a specific substring. Return true when the substring is found, or return false when not found. This function is not case-sensitive.
+        /// </summary>
+        /// <definition>
+        /// endsWith('$lttext$gt', '$ltsearchText$gt')
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The string to check</parameter>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The ending substring to find</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>true or false</value>
+        ///     <type>Boolean</type>
+        ///     <description>Return true when the ending substring is found. Return false when not found.</description>
+        /// </returns>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 2)

ExpressionEngine/Functions/Implementations/StringFunctions/FormatNumberFunction.cs

@@ -11,6 +11,23 @@ public FormatNumberFunction() : base("formatNumber")
         {
         }
 
+        /// <functionName>formatNumber</functionName>
+        /// <summary>
+        /// Return a number as a string that's based on the specified format.
+        /// </summary>
+        /// <definition>
+        /// formatNumber($ltnumber$gt, $ltformat$gt, $ltlocale$gt)
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$ltnumber$gt" required="Yes" type="Integer or Double">The value that you want to format.</parameter>
+        ///     <parameter def="$ltformat$gt" required="Yes" type="String">A composite format string that specifies the format that you want to use. For the supported numeric format strings, see Standard numeric format strings, which are supported by number.ToString($ltformat$gt, $ltlocale$gt).</parameter>
+        ///     <parameter def="$ltlocale$gt" required="Mo" type="String">The locale to use as supported by <c>number.ToString($ltformat$gt, $ltlocale$gt)</c>. If not specified, the default value is <c>en-us</c>.</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>$ltformatted-number$gt</value>
+        ///     <type>String</type>
+        ///     <description>The specified number as a string in the format that you specified. You can cast this return value to an <c>int</c> or <c>float</c>.</description>
+        /// </returns>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 2 || parameters.Length > 3)

ExpressionEngine/Functions/Implementations/StringFunctions/LengthFunction.cs

@@ -13,6 +13,22 @@ public LengthFunction() : base("length")
         {
         }
 
+        /// <functionName>length</functionName>
+        /// <summary>
+        /// Return the number of items in a collection.
+        /// </summary>
+        /// <definition>
+        /// length('$ltcollection$gt')
+        /// length([$ltcollection$gt])
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$ltcollection$gt" required="Yes" type="String or Array">The collection with the items to count</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>$ltlength-or-count$gt</value>
+        ///     <type>Integer</type>
+        ///     <description>The number of items in the collection</description>
+        /// </returns>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length != 1)

ExpressionEngine/Functions/Implementations/StringFunctions/ReplaceFunction.cs

@@ -10,6 +10,24 @@ public ReplaceFunction() : base("replace")
         {
         }
 
+        
+        /// <functionName>replace</functionName>
+        /// <summary>
+        /// Replace a substring with the specified string, and return the result string. This function is case-sensitive.
+        /// </summary>
+        /// <definition>
+        /// replace('$lttext$gt', '$ltoldText$gt', '$ltnewText$gt')
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The string that has the substring to replace</parameter>
+        ///     <parameter def="$ltoldText$gt" required="Yes" type="String">The substring to replace</parameter>
+        ///     <parameter def="$ltnewtext$gt" required="Yes" type="String">The replacement string</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>$ltupdated-text$gt</value>
+        ///     <type>String</type>
+        ///     <description>The updated string after replacing the substring<br/>If the substring is not found, return the original string.</description>
+        /// </returns>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 3)

ExpressionEngine/Functions/Implementations/StringFunctions/SplitFunction.cs

@@ -12,6 +12,24 @@ public SplitFunction() : base("split")
         {
         }
 
+        /// <functionName>split</functionName>
+        /// <summary>
+        /// Return an array that contains substrings, separated by commas, based on the specified delimiter character in the original string.
+        /// </summary>
+        /// <definition>
+        /// split('$lttext$gt', '$ltdelimiter$gt')
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The string to separate into substrings based on the specified delimiter in the original string</parameter>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The character in the original string to use as the delimiter</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>[$ltsubstring1$gt,$ltsubstring2$gt,...]</value>
+        ///     <type>Array</type>
+        ///     <description>An array that contains substrings from the original string, separated by commas</description>
+        /// </returns>
+        // [ArguementAttribute()]
+        // [ArguementAttribute()]
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 2)

ExpressionEngine/Functions/Implementations/StringFunctions/StartsWithFunction.cs

@@ -10,6 +10,36 @@ public StartsWithFunction() : base("startsWith")
         {
         }
 
+        /// <functionName>startsWith</functionName>
+        /// <summary>
+        /// Check whether a string starts with a specific substring. Return true when the substring is found, or return false when not found. This function is not case-sensitive.
+        /// </summary>
+        /// <definition>
+        /// startsWith('$lttext$gt', '$ltsearchText$gt')
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The string to check</parameter>
+        ///     <parameter def="$ltsearchText$gt" required="Yes" type="String">The starting string to find</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>true or false</value>
+        ///     <type>Boolean</type>
+        ///     <description>Return true when the starting substring is found. Return false when not found.</description>
+        /// </returns>
+        /// <example>
+        /// This example checks whether the "hello world" string starts with the "hello" substring:
+        /// <code>
+        /// startsWith('hello world', 'hello')
+        /// </code>
+        /// And returns this result: <c>true</c>
+        ///
+        ///
+        /// This example checks whether the "hello world" string starts with the "greetings" substring:
+        /// <code>
+        /// startsWith('hello world', 'greetings')
+        /// </code>
+        /// And returns this result: <c>false</c>
+        /// </example>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 2)

ExpressionEngine/Functions/Implementations/StringFunctions/SubstringFunction.cs

@@ -10,6 +10,34 @@ public SubstringFunction() : base("substring")
         {
         }
 
+
+        /// <functionName>substring</functionName>
+        /// <summary>
+        /// Return characters from a string, starting from the specified position, or index. Index values start with the number 0.
+        /// </summary>
+        /// <definition>
+        /// substring('$lttext$gt', $ltstartIndex$gt, $ltlength$gt)
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The string whose characters you want</parameter>
+        ///     <parameter def="$ltstartIndex$gt" required="Yes" type="Integer">A positive number equal to or greater than 0 that you want to use as the starting position or index value</parameter>
+        ///     <parameter def="$ltlength$gt" required="Yes" type="Integer">A positive number of characters that you want in the substring</parameter>
+        /// </parameters>
+        /// <note>
+        /// Make sure that the sum from adding the startIndex and length parameter values is less than the length of the string that you provide for the text parameter. Otherwise, you get an error, unlike similar functions in other languages where the result is the substring from the startIndex to the end of the string. The length parameter is optional and if not provided, the substring() function takes all the characters beginning from startIndex to the end of the string.
+        /// </note>
+        /// <returns>
+        ///     <value>$ltsubstring-result$gt</value>
+        ///     <type>String</type>
+        ///     <description>A substring with the specified number of characters, starting at the specified index position in the source string</description>
+        /// </returns>
+        /// <example>
+        /// This example creates a five-character substring from the specified string, starting from the index value 6:
+        /// <code>
+        /// substring('hello world', 6, 5)
+        /// </code>
+        /// And returns this result: <c>"world"</c>
+        /// </example>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length < 2 || parameters.Length > 3)
@@ -20,9 +48,10 @@ public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[
             var str = parameters[0].GetValue<string>();
             var startIndex = parameters[1].GetValue<int>();
 
-            if (parameters.Length <= 2) return new ValueTask<ValueContainer>(new ValueContainer(str.Substring(startIndex)));
-            
-            
+            if (parameters.Length <= 2)
+                return new ValueTask<ValueContainer>(new ValueContainer(str.Substring(startIndex)));
+
+
             var length = parameters[2].GetValue<int>();
 
             if (startIndex + length > str.Length)

ExpressionEngine/Functions/Implementations/StringFunctions/ToLowerFunction.cs

@@ -10,6 +10,28 @@ public ToLowerFunction() : base("toLower")
         {
         }
 
+        /// <functionName>toLower</functionName>
+        /// <summary>
+        /// Return a string in lowercase format. If a character in the string doesn't have a lowercase version, that character stays unchanged in the returned string.
+        /// </summary>
+        /// <definition>
+        /// toLower('$lttext$gt')
+        /// </definition>
+        /// <parameters>
+        ///     <parameter def="$lttext$gt" required="Yes" type="String">The string to return in lowercase format</parameter>
+        /// </parameters>
+        /// <returns>
+        ///     <value>$ltlowercase-text$gt</value>
+        ///     <type>String</type>
+        ///     <description>The original string in lowercase format</description>
+        /// </returns>
+        /// <example>
+        /// This example converts this string to lowercase:
+        /// <code>
+        /// toLower('Hello World')
+        /// </code>
+        /// And returns this result: <c>"hello world"</c>
+        /// </example>
         public override ValueTask<ValueContainer> ExecuteFunction(params ValueContainer[] parameters)
         {
             if (parameters.Length != 1)