docs: Update jsdoc for ProgramCall.js (#236)

Author: abmusse

lib/ProgramCall.js

@@ -19,10 +19,22 @@
 
 class ProgramCall {
   /**
-   * @description creates a new ProgramCall object
+   * ProgramCall Configuration
+   * @typedef {object} programCallConfig
+   * @property {string} lib - The library where the program exists.
+   * @property {string} [error=fast] - Determines action when an error is encountered.
+   * Valid options are ``on``, ``off``, or ``fast``. Default is ``fast``. Using ``on``
+   * will cause the script execution to stop and log a full error report.
+   * Using ``off`` or ``fast`` continues executing the script. The Difference is that ``fast``
+   * will log a brief error report and ``off`` will not.
+   * @property {string} [func] - The target function of the service program.
+   */
+
+  /**
+   * @description Creates a new ProgramCall object.
    * @constructor
-   * @param {string} program
-   * @param {object} [options]
+   * @param {string} program - The program or service program name.
+   * @param {programCallConfig} [options]
    */
   constructor(program, options = {}) {
     this.xml = `<pgm name='${program}'`;
@@ -32,7 +44,8 @@ class ProgramCall {
   }
 
   /**
-   * Internal function to handle ds and data within <parm> node
+   * @private
+   * @description Internal function to handle ds and data within <parm> node
    * There is an open propsal to add private methods to JS.
    * https://github.com/tc39/proposal-private-methods
    * We should update to use private methods in the future.
@@ -66,8 +79,54 @@ class ProgramCall {
   }
 
   /**
-  * @description adds a parameter to the program XML
-  * @param {object} parmeter
+  * Data Object Within DS
+  * @typedef {object} data
+  * @property {string} type - The XMLSERVICE data type.
+  * @property {string} value - The value of the data.
+  * @property {string} [name] - The name of the data.
+  * @property {string} [varying] - Marks data as a varying length character type
+  * (ie. varchar) and specifies the size of the length prefix. Valid values are ``on``, ``off``,
+  *  ``2``, or '4' (``on`` is equivalent to ``2``). NOTE: This is only valid for character types.
+  * @property {string} [enddo] - The label that marks the end of the ``dou``` (do until) label.
+  * @property {string} [setlen] - The label to set the length of the data
+  * based on the matching ``len`` label.
+  * @property {string} [hex] - Whether to interpret the data as hex.
+  * Valid values are ``on`` or ``off``. Default is ``off``.
+  * @property {string} [trim] - Whether to allow trim. Valid values are ``on`` or ``off``.
+  * Default is ``on``.
+  */
+
+  /**
+  * Parameter Config Object
+  * @typedef {object} parameterConfig
+  * @property {string} type - The XMLSERVICE data type or ds for a data structure.
+  * @property {string} value - The value of the data.
+  * @property {string} [name] - The name of the parameter.
+  * @property {data[]} [fields] - The array of data objects for a ds.
+  * @property {string} [io] - Whether the parameter is used for input, output, or both.
+  * Valid values are ``in``, ``out``, or ``both``.
+  * @property {string} [by] - Whether to pass the parameter by reference or value.
+  * Valid values are ``ref`` or ``val``. NOTE: Pass by value requires ``XMLSERVICE >= 1.9.9.3``.
+  * @property {string} [dim] - Sets ds array dimension value.
+  * @property {string} [dou] - Marks ds with do until label.
+  * @property {string} [len] - Marks ds with len label.
+  * @property {string} [varying] -  Marks data as a varying length character type
+  * (ie. varchar) and specifies the size of the length prefix. Valid values are 'on', ``off``,
+  * ``2``, or ``4`` (``on`` is equivalent to ``2``). NOTE: This is only valid for character types.
+  * @property {string} [enddo] - The label that marks the end of the ``dou`` (do until) label.
+  * @property {string} [setlen] - The label to set the length of the data
+  * based on the matching ``len`` label.
+  * @property {string} [hex] - Whether to interpret the data as hex.
+  * Valid values are ``on`` or ``off``. Default is ``off``.
+  * @property {string} [trim] - Whether to allow trim. Valid values are ``on`` or ``off``.
+  * Default is ``on``.
+  */
+
+  /**
+  * @description Adds a parameter to the program XML.
+  * @param {parameterConfig} parmeter
+  * @throws Will throw an error when the first parameter is not an object.
+  * @throws Will throw an error when the object does set the ``type`` key.
   */
   addParam(parameter = {}) {
     if (typeof parameter !== 'object') {
@@ -88,8 +147,32 @@ class ProgramCall {
   }
 
   /**
-   * @description adds a return element to the program XML
-   * @param {object} data
+  * Return Config Object
+  * @typedef {object} returnConfig
+  * @property {string} type - The XMLSERVICE data type or ds for a data structure.
+  * @property {string} value - The value of the data node.
+  * @property {string} [name] - The name of the return data.
+  * @property {data[]} [fields] - The array of data objects for a ds.
+  * @property {string} [dim] - Sets ds array dimension value.
+  * @property {string} [dou] - Marks ds with do until label.
+  * @property {string} [len] - Marks ds with len label.
+  * @property {string} [varying] - Marks data as a varying length character type
+  * (ie. varchar) and specifies the size of the length prefix. Valid values are ``on``, ``off``,
+  * ``2``, or ``4`` (``on`` is equivalent to ``2``). NOTE: This is only valid for character types.
+  * @property {string} [enddo] - The label that marks the end of the ``dou`` (do until) label.
+  * @property {string} [setlen] - The label to set the length of the data
+  * based on the matching ``len`` label.
+  * @property {string} [hex] - Whether to interpret the input as hex.
+  * Valid values are ``on`` or ``off``. Default is ``off``.
+  * @property {string} [trim] - Whether to allow trim. Valid values are ``on`` or ``off``.
+  * Default is ``on``.
+  */
+
+  /**
+   * @description Specifies the type of the return value for the service program function.
+   * @param {returnConfig} data
+   * @throws Will throw an error when the first parameter is not an object.
+   * @throws Will throw an error when the object does set the ``type`` key.
    */
   addReturn(data = {}) {
     if (typeof data !== 'object') {
@@ -105,8 +188,7 @@ class ProgramCall {
   }
 
   /**
-   * @description returns the current program XML
-   * @returns {string} - the generated program XML
+   * @returns {string} the generated program XML
    */
   toXML() {
     return `${this.xml}</pgm>`;