From 0dc993dd85f66d82320728c7d413113ad5804933 Mon Sep 17 00:00:00 2001 From: Abdirahim Musse <33973272+abmusse@users.noreply.github.com> Date: Sun, 29 Mar 2020 21:26:45 -0500 Subject: [PATCH] docs: Update jsdoc for ProgramCall.js --- lib/ProgramCall.js | 102 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 92 insertions(+), 10 deletions(-) diff --git a/lib/ProgramCall.js b/lib/ProgramCall.js index e7894e13..6613315c 100644 --- a/lib/ProgramCall.js +++ b/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 = ` node + * @private + * @description Internal function to handle ds and data within 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}`;