chore(docs): add documentation for functions

.copilot/settings.txt

@@ -0,0 +1,98 @@
+// Settings for Copilot usage in this project
+
+// 1. Code Generation Guidelines:
+// - Always generate code in IEC61131-3 Structured Text (ST) format.
+// - All functions must include inline documentation in the following format:
+//   /// <Brief description of the function>
+//   /// Input: <Parameter descriptions>
+//   /// Returns: <Return value description>
+// Example:
+//   /// Converts a subset of a CHAR array to a string.
+//   /// Input: arr - Input CHAR array to convert.
+//   ///        startIdx - Start index of the subset.
+//   ///        endIdx - End index of the subset.
+//   /// Returns: A string representation of the specified subset of the CHAR array.
+//   FUNCTION ToString : STRING
+//       VAR_INPUT
+//           arr : ARRAY[*] OF CHAR; // Input CHAR array to convert
+//           startIdx : INT; // Start index of the subset
+//           endIdx : INT; // End index of the subset
+//       END_VAR
+//       ;
+//   END_FUNCTION
+
+// 2. Unit Test Guidelines:
+// Test-Files shall be stored in the folder `test`.
+// - Use AxUnit for unit testing.
+// - Tests should follow the structure below:
+//   - {TestFixture} to define a test class.
+//   - {Test} for individual test methods.
+//   - Support parameterized tests using {Test(...)} annotations.
+// Example:
+//   USING AxUnit.Assert;
+//   NAMESPACE AnyNamespace
+//       {TestFixture}
+//       CLASS TestClass
+//           VAR
+//               val : LINT;
+//               val2 : ULINT;
+//               res : BOOL;
+//           END_VAR
+//
+//           {Test}
+//           METHOD PUBLIC Convert_STRING_0_TO_LINT_0
+//               res := StringToAnyInt(str := '0', value => val);
+//               Equal(expected := 0, actual := val);
+//               Equal(expected := TRUE, actual := res);
+//           END_METHOD
+//
+//           {Test(str := STRING#'18446744073709551746', value := ULINT#0, success := FALSE)}
+//           {Test(str := STRING#'18446744073709551800', value := ULINT#0, success := FALSE)}
+//           METHOD PUBLIC Convert_STRING_TO_ULINT
+//               VAR_INPUT
+//                   str : STRING;
+//                   value : ULINT;
+//                   success : BOOL;
+//               END_VAR
+//               VAR_TEMP
+//                   resVal : ULINT;
+//               END_VAR
+//               res := StringToULint(str := str, value => resVal);
+//               Equal(expected := value, actual := resVal);
+//               Equal(expected := success, actual := res);
+//           END_METHOD
+//       END_CLASS
+//   END_NAMESPACE
+
+// 3. Documentation Rules:
+// - All types, functions, and methods must include inline documentation.
+// - Use the following format for documentation:
+//   /// <Brief description>
+//   /// Input: <Parameter descriptions>
+//   /// Returns: <Return value description>
+// - Ensure that all parameters and return values are clearly described.
+
+// 4. File Organization Rules:
+// - Place all source files in the `src` folder.
+// - Place all test files in the `test` folder.
+// - Use descriptive filenames that reflect the functionality of the file.
+
+// 5. Naming Conventions:
+// - Use PascalCase for function and type names (e.g., `ToString`, `SimotionDateTime`).
+
+// 6. Code Format Rules:
+// - Always generate code in IEC61131-3 Structured Text (ST) format.
+
+// 7. Constant Declaration Rules:
+// - Constants, except for `INT`, `BOOL` and `LREAL`, must always include explicit type annotations.
+//   Examples:
+//     - REAL#1.0
+//     - ULINT#1
+//     - SINT#23
+
+// 8. Return Statement Rules:
+// - `RETURN` cannot take a return value.
+// - Return values must always be assigned to the function or method name before using `RETURN`.
+//   Example:
+//     FunctionName := ReturnValue;
+//     RETURN;

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "conventionalCommits.scopes": [
+        "deps"
+    ]
+}

src/TRUNC.st

@@ -1,5 +1,12 @@
 NAMESPACE Simatic.Ax.Conversion
 
+    /// Truncates a 64-bit floating-point number (LREAL) to an integer.
+    ///
+    /// This function truncates the input LREAL value to the nearest integer toward zero.
+    /// It handles both positive and negative values.
+    ///
+    /// @param Value The LREAL value to truncate.
+    /// @return The truncated integer value.
     FUNCTION TRUNC : DINT
         VAR_INPUT
             Value : LREAL;
@@ -16,6 +23,13 @@ NAMESPACE Simatic.Ax.Conversion
         END_IF;
     END_FUNCTION
 
+    /// Truncates a 32-bit floating-point number (REAL) to an integer.
+    ///
+    /// This function truncates the input REAL value to the nearest integer toward zero.
+    /// It handles both positive and negative values.
+    ///
+    /// @param Value The REAL value to truncate.
+    /// @return The truncated integer value.
     FUNCTION TRUNC : DINT
         VAR_INPUT
             Value : REAL;
@@ -31,4 +45,5 @@ NAMESPACE Simatic.Ax.Conversion
             END_IF;
         END_IF;
     END_FUNCTION
+
 END_NAMESPACE

src/strings/AnyIntToString.st

@@ -2,6 +2,16 @@ USING System.Strings;
 USING System.Math;
 
 NAMESPACE Simatic.Ax.Conversion
+
+    /// Converts a signed 64-bit integer (LINT) to its string representation.
+    ///
+    /// This function converts a signed 64-bit integer to a string, optionally adding a sign
+    /// based on the specified conversion mode. It handles negative values and ensures the
+    /// correct number of digits are included in the output.
+    ///
+    /// @param value The signed 64-bit integer to convert.
+    /// @param mode The conversion mode (e.g., force sign).
+    /// @return A string representation of the input integer.
     FUNCTION INTERNAL AnyIntToString : STRING
         VAR_INPUT
             value : LINT;
@@ -42,6 +52,15 @@ NAMESPACE Simatic.Ax.Conversion
         END_FOR;
     END_FUNCTION
 
+    /// Converts an unsigned 64-bit integer (ULINT) to its string representation.
+    ///
+    /// This function converts an unsigned 64-bit integer to a string, optionally adding a sign
+    /// based on the specified conversion mode. It ensures the correct number of digits are
+    /// included in the output.
+    ///
+    /// @param value The unsigned 64-bit integer to convert.
+    /// @param mode The conversion mode (e.g., force sign).
+    /// @return A string representation of the input integer.
     FUNCTION INTERNAL ULintToString : STRING
         VAR_INPUT
             value : ULINT;
@@ -80,4 +99,5 @@ NAMESPACE Simatic.Ax.Conversion
             ULintToString := Concat(ULintToString, s);
         END_FOR;
     END_FUNCTION
+
 END_NAMESPACE

src/strings/ArrayToString.st

@@ -1,6 +1,18 @@
 USING System.Strings;
 
 NAMESPACE Simatic.Ax.Conversion.Arrays
+
+    /// Converts a subset of a character array to a string.
+    /// 
+    /// This function takes a character array and converts a specified range of elements
+    /// (from `startIdx` to `endIdx`) into a string. If the range is invalid or exceeds
+    /// the array bounds, an empty string is returned. The maximum string length is limited
+    /// to `MAX_STR_LEN`.
+    ///
+    /// @param arr The input character array.
+    /// @param startIdx The starting index of the range to convert.
+    /// @param endIdx The ending index of the range to convert.
+    /// @return A string representation of the specified range of the array.
     FUNCTION ToString : STRING
         VAR_INPUT
             arr : ARRAY[*] OF CHAR;
@@ -47,6 +59,14 @@ NAMESPACE Simatic.Ax.Conversion.Arrays
 
     END_FUNCTION
 
+    /// Converts an entire character array to a string.
+    ///
+    /// This function takes a character array and converts all its elements into a string.
+    /// If the array length exceeds `MAX_STR_LEN`, the resulting string is truncated to
+    /// the maximum allowed length.
+    ///
+    /// @param arr The input character array.
+    /// @return A string representation of the entire array.
     FUNCTION ToString : STRING
         VAR_INPUT
             arr : ARRAY[*] OF CHAR;
@@ -74,4 +94,5 @@ NAMESPACE Simatic.Ax.Conversion.Arrays
         END_FOR;
 
     END_FUNCTION
+
 END_NAMESPACE

src/strings/ConversionMode.st

@@ -1,5 +1,12 @@
 NAMESPACE Simatic.Ax.Conversion
+
+    /// Represents the conversion mode for integer-to-string operations.
+    ///
+    /// This type defines the available modes for formatting integer-to-string conversions:
+    /// - `NONE`: No special formatting is applied.
+    /// - `FORCE_SIGN`: Forces the inclusion of a '+' sign for positive numbers.
     TYPE
         ConversionMode : WORD (NONE := WORD#16#0000, FORCE_SIGN := WORD#16#0001) := NONE;
     END_TYPE
+
 END_NAMESPACE

src/strings/CountDigits.st

@@ -1,4 +1,13 @@
 NAMESPACE Simatic.Ax.Conversion
+
+    /// Counts the number of digits in a signed 64-bit integer (LINT).
+    ///
+    /// This function calculates the number of decimal digits in the given signed 64-bit integer.
+    /// It iteratively checks the range of the value against increasing powers of 10.
+    /// The maximum number of digits it can handle is defined by `MAX_DIGITS`.
+    ///
+    /// @param value The signed 64-bit integer whose digits are to be counted.
+    /// @return The number of decimal digits in the input value.
     FUNCTION CountDigits : INT
         VAR_INPUT
             value : LINT;
@@ -21,6 +30,14 @@ NAMESPACE Simatic.Ax.Conversion
         CountDigits := 19;
     END_FUNCTION    
 
+    /// Counts the number of digits in an unsigned 64-bit integer (ULINT).
+    ///
+    /// This function calculates the number of decimal digits in the given unsigned 64-bit integer.
+    /// It iteratively checks the range of the value against increasing powers of 10.
+    /// The maximum number of digits it can handle is defined by `MAX_DIGITS`.
+    ///
+    /// @param value The unsigned 64-bit integer whose digits are to be counted.
+    /// @return The number of decimal digits in the input value.
     FUNCTION CountDigits : INT
         VAR_INPUT
             value : ULINT;
@@ -42,4 +59,5 @@ NAMESPACE Simatic.Ax.Conversion
         END_FOR;
         CountDigits := 20;
     END_FUNCTION    
+
 END_NAMESPACE

src/strings/HexToString.st

@@ -2,7 +2,15 @@ USING System;
 USING System.Strings;
 
 NAMESPACE Simatic.Ax.Conversion
-
+
+    /// Converts a BYTE value to its hexadecimal string representation.
+    ///
+    /// This function takes a BYTE value and converts it into a two-character hexadecimal string.
+    /// It splits the BYTE into two nibbles, converts each nibble to its hexadecimal character,
+    /// and concatenates the results.
+    ///
+    /// @param b The BYTE value to convert.
+    /// @return A two-character string representing the hexadecimal value of the input BYTE.
     FUNCTION PUBLIC ByteToString : STRING
         VAR_INPUT
             b : BYTE;
@@ -18,6 +26,13 @@ NAMESPACE Simatic.Ax.Conversion
 
     END_FUNCTION
 
+    /// Converts a nibble (4 bits) to its hexadecimal character representation.
+    ///
+    /// This function takes a nibble (a value between 0 and 15) and returns the corresponding
+    /// hexadecimal character (0-9, A-F) using a lookup table.
+    ///
+    /// @param nibble The nibble value to convert (0-15).
+    /// @return The hexadecimal character corresponding to the input nibble.
     FUNCTION INTERNAL LookUpHEX : CHAR
         VAR_INPUT
             nibble : BYTE;