From 70be44fef9016e588df838c77673655cecb2da85 Mon Sep 17 00:00:00 2001
From: Johannes Hoermann <j.hoermann@adito.de>
Date: Fri, 30 Nov 2018 14:24:33 +0100
Subject: [PATCH] update lib documentation

---
 others/guide/how to write JDito code.adoc | 20 ++++++++-
 others/guide/instanceableLibExample.adoc  | 55 +++++++++++++++++++++++
 others/guide/staticLibExample.adoc        |  5 ++-
 3 files changed, 76 insertions(+), 4 deletions(-)
 create mode 100644 others/guide/instanceableLibExample.adoc

diff --git a/others/guide/how to write JDito code.adoc b/others/guide/how to write JDito code.adoc
index 5f7169bc097..cd9eef70656 100644
--- a/others/guide/how to write JDito code.adoc	
+++ b/others/guide/how to write JDito code.adoc	
@@ -6,7 +6,7 @@ How to write JDito code
 == basics ==
 * Keep everything english. Every title, caption, messages, comments, etc. should be english. Add german translation to the languages if necessary.
 * in JavaScript-Strings use `"` instead of `'` - even if its only 1 character. `'` is for SQL (within JS-Strings)
- 
+* Parameters should not start with p because they are usable like normal variables. There is no real benefit from naming them p****.
 
 == code structure ==
 === vars and others (var, let) ===
@@ -147,7 +147,23 @@ So just start your functions / methods name with a _ if you need private methods
 == JS-Doc ==
 
 <1> JS-Doc comment: http://usejsdoc.org/
-<2> use the correct form for optional/required parameters: http://usejsdoc.org/tags-param.html
+<2> use the correct form for optional/required parameters: http://usejsdoc.org/tags-param.html 
+Optional parameter: [alias=the current alias]
+Required parameter: alias
+[source,javascript]
+----
+/**
+ * Description...
+ * ...
+ *  
+ * @param {String} [alias=the current alias] the database alias where the condition shall be executed later (important for column types of preparedStatements)
+ * @example Here is an example
+ * @class
+ */
+function SqlCondition(alias) {
+...
+}
+----
 <3> examples are useful on more complex functions
 <4> constructor function; init properties (do not set functions ("methods") here!)
 <5> add functions ("methods") to the prototype, they are available through the prototype chain
diff --git a/others/guide/instanceableLibExample.adoc b/others/guide/instanceableLibExample.adoc
new file mode 100644
index 00000000000..bbc7a88b001
--- /dev/null
+++ b/others/guide/instanceableLibExample.adoc
@@ -0,0 +1,55 @@
+= Example for a instanceable Lib =
+
+Remember to always change the comments to fit your class! +
+Use speaking names for ALL variables, classes and functions!
+
+[source,javascript]
+----
+import("...");
+
+/**
+ * instanceable example Utility class;
+ * 
+ * @param {String} param1 is for ...
+ * 
+ * @example var myUtil = new UtilClass("-");
+ * @class
+ */
+function UtilClass(param1) {
+    // here is the constructor.
+    // create class variables like this:
+    this.myVariable = param1;
+}
+
+/**
+ * a public function
+ * 
+ * @param {String} param1 is for ...
+ * @param {String} param2 is for ...
+ * 
+ * @example var myResult = myUtil.myFunction("p1", "p2");
+ * 
+ * @return {String} a result
+ */
+UtilClass.prototype.myFunction = function(param1, param2) {
+    return this._privateStaticFunction1(param1, param2, this.myVariable);
+}
+
+/**
+ * a private function
+ * 
+ * @param {String} param1 is for ...
+ * @param {String} param2 is for ...
+ * @param {String} param3 is for ...
+ * 
+ * @return {String} a result
+ */
+UtilClass.prototype._myPrivateFunction = function(param1, param2, param3) {
+    if(param1 && param2 && param3) {
+        ...
+        return param1 + param3 + param2;
+    }
+
+    return "";
+}
+----
\ No newline at end of file
diff --git a/others/guide/staticLibExample.adoc b/others/guide/staticLibExample.adoc
index 2b668afeb18..88d7ad1e4be 100644
--- a/others/guide/staticLibExample.adoc
+++ b/others/guide/staticLibExample.adoc
@@ -1,6 +1,7 @@
 = Example for a static Lib =
 
-Remember to always change the comments to fit your class!
+Remember to always change the comments to fit your class! +
+Use speaking names for ALL variables, classes and functions!  
 
 [source,javascript]
 ----
@@ -12,7 +13,7 @@ import("...");
  * Do not create an instance of this!
  * @class
  */
-function ExampleUtils() {}
+function ExampleUtils() {} // leave this function empty! A constructor is not needed for static functions.
 
 /**
  * a public static function
-- 
GitLab