From 469e6601ba8dfa1854e8d6e20063f82a4e575f32 Mon Sep 17 00:00:00 2001
From: Martin Karkowski <m.karkowski@zema.de>
Date: Wed, 19 Jan 2022 08:25:23 +0100
Subject: [PATCH] adding comments

---
 lib/communication/index.nodejs.ts          |   2 +
 lib/types/nope/nopeDescriptor.interface.ts | 122 ++++++++++++++++++++-
 2 files changed, 123 insertions(+), 1 deletion(-)

diff --git a/lib/communication/index.nodejs.ts b/lib/communication/index.nodejs.ts
index b1c0a07..ea1e100 100644
--- a/lib/communication/index.nodejs.ts
+++ b/lib/communication/index.nodejs.ts
@@ -1,9 +1,11 @@
 /**
+ * @module communication
  * @author Martin Karkowski
  * @email m.karkowski@zema.de
  * @create date 2021-08-04 15:30:10
  * @modify date 2022-01-10 16:01:15
  * @desc [description]
+ * 
  */
 
 export { Bridge } from "./bridge";
diff --git a/lib/types/nope/nopeDescriptor.interface.ts b/lib/types/nope/nopeDescriptor.interface.ts
index afa76ee..b39647a 100644
--- a/lib/types/nope/nopeDescriptor.interface.ts
+++ b/lib/types/nope/nopeDescriptor.interface.ts
@@ -6,6 +6,9 @@
  * @desc [description]
  */
 
+/**
+ * Valid Descriptor types
+ */
 export type INopeDescriptorSchemaBaseTypes =
   | "string"
   | "number"
@@ -15,13 +18,77 @@ export type INopeDescriptorSchemaBaseTypes =
   | "boolean"
   | "null"
   | "function";
+
+/**
+ * A (JSON-Schema and) Nope-Descriptor allows to use multiple types. 
+ * Therefore this type uses some additonal types. Alternativly, a reference
+ * **`$ref`** can be used to describe some data. Therefore the schema
+ * must be availalbe on the reference.
+ */
 export type INopeDescriptorSchemaTypes =
   | INopeDescriptorSchemaBaseTypes
   | Array<INopeDescriptorSchemaBaseTypes>
   | { $ref: string };
 
 /**
- * Generic Descriptor of an Version.
+ * # INopeDescriptor
+ * 
+ * A generic descriptor of data or a function. This descriptors will be used to describe `NoPE` data-points or functions. The Descriptor is based on **JSON-Schemas** (see [here](https://json-schema.org/) for more details).
+ * 
+ * 
+ * ## Describing data
+ * 
+ * A valid example - *describing some data* - is given below (in the form of `JSON`-data). This example matches a **JSON-Schema**: * 
+ * 
+ * ```json
+ * {
+ *  "title": "Person",
+ *  "type": "object",
+ *  "properties": {
+ *    "firstName": {
+ *      "type": "string",
+ *      "description": "The person's first name."
+ *    },
+ *    "lastName": {
+ *      "type": "string",
+ *      "description": "The person's last name."
+ *    },
+ *    "age": {
+ *      "description": "Age in years which must be equal to or greater than zero.",
+ *      "type": "integer",
+ *      "minimum": 0
+ *    }
+ *  }
+ * }
+ * ```
+ * ## Describing functions
+ * 
+ * A valid example - *describing a function* - is given below (in the form of `JSON`-data):
+ * 
+ * ```json
+ * {
+ *  "type": "function",
+ *  "description": "A Sample Function",
+ *  "inputs": [
+ *    {
+ *      "name": "parameter_01",
+ *      "description": "The first Parameter of the Function",
+ *      "schema": {
+ *        "type":"string",
+ *        "maxLength": 10
+ *      }
+ *    },
+ *    {
+ *      "name": "parameter_02",
+ *      "description": "The second Parameter of the Function. This is optional",
+ *      "optional": true,
+ *      "schema": {
+ *        "type":"boolean"
+ *      }
+ *    }
+ *  ]  
+ * }
+ * ```
  *
  * @export
  * @interface INopeDescriptor
@@ -89,8 +156,16 @@ export interface INopeDescriptor {
   // String Validation
   /////////////////////////////////////////////////
 
+  /**
+   * Max length of the string.
+   */
   maxLength?: number;
+
+  /**
+   * Min length of the string.
+   */
   minLength?: number;
+
   /**
    * This is a regex string that the value must
    * conform to
@@ -102,8 +177,20 @@ export interface INopeDescriptor {
   /////////////////////////////////////////////////
   additionalItems?: boolean | INopeDescriptor;
   items?: INopeDescriptor | INopeDescriptor[];
+
+  /**
+   * max. amount of items, the array is allwoed to contain.
+   */
   maxItems?: number;
+
+  /**
+   * min. amount of items, the array must contain.
+   */
   minItems?: number;
+
+  /**
+   * Flag, to define, that every item in the array must be unique.
+   */
   uniqueItems?: boolean;
 
   /////////////////////////////////////////////////
@@ -181,14 +268,47 @@ export interface INopeDescriptor {
    */
   not?: INopeDescriptor;
 
+  /**
+   * Data-Field, which must be filled out, if we are describing a function. This will describe the entire data of the inputs.
+   */
   inputs?: Array<INopeDescriptorFunctionParameter>;
 
+  /**
+   * The Return (output) of a function. This must be provided if the type is set to ***function*** {@link INopeDescriptor.type}
+   */
   outputs?: Array<INopeDescriptorFunctionParameter> | INopeDescriptor;
 }
 
+/**
+ * Helper, to describe a Function Parameter
+ */
 export interface INopeDescriptorFunctionParameter {
+  /**
+   * Name, which is used in the function header
+   *
+   * @type {string}
+   * @memberof INopeDescriptorFunctionParameter
+   */
   name: string;
+  /**
+   * Description of the parameter. Similar to a comment, describing a parameter
+   *
+   * @type {string}
+   * @memberof INopeDescriptorFunctionParameter
+   */
   description?: string;
+  /**
+   * Flag, showing whether the parameter is *optional* or not.
+   *
+   * @type {boolean}
+   * @memberof INopeDescriptorFunctionParameter
+   */
   optional?: boolean;
+  /**
+   * The Schema used to describe the parameter. see {@link INopeDescriptor}
+   *
+   * @type {INopeDescriptor}
+   * @memberof INopeDescriptorFunctionParameter
+   */
   schema: INopeDescriptor;
 }