refactor documentation

others/guide/HowToSqlConditionLib.adoc

@@ -159,7 +159,7 @@ var productPriceData = (db.ROW, db.array(SqlCondition.begin()
 With a loop:
 [source,javascript]
 ----
-function _getClassificationCondition(include) 
+function _getClassificationCondition(pInclude) 
 {
     var resultingCondition = new SqlCondition();
     resultingCondition.andPrepare("SALESPROJECT_CLASSIFICATION.SALESPROJECT_ID", salesprojectId)
@@ -169,7 +169,7 @@ function _getClassificationCondition(include)
 
     entryKeywords.forEach(function(entry) 
     {
-        if (include)
+        if (pInclude)
         {
             typeCondition.orPrepare("SALESPROJECT_CLASSIFICATION.TYPE", entry[0], "# = ?");
         }

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****.
+* Parameters should start with p.
 
 == code structure ==
 === vars and others (var, let) ===
@@ -23,7 +23,7 @@ for (i = 0, i < dataLen; i++)
     //code here
 }
 
-myArray.forEach(function(item) 
+myArray.forEach(function(pItem) 
 {
     // Do something
 });
@@ -111,7 +111,7 @@ Definition:
  * @param {String} [alias=the current alias] the database alias where the condition shall be executed later (important for column types of preparedStatements) <2>
  * @example //TODO: add missing example <3>
  */
-function SqlCondition(alias) <4>
+function SqlCondition(pAlias) <4>
 {
    //setting null is only needed to provide autocomplete for the ADITO-designer
     this.preparedValues = null;
@@ -123,13 +123,13 @@ function SqlCondition(alias) <4>
  * @param {String} cond the condition string which shall be appended
  * @return {Object} current SqlCondition-object
  */
-SqlCondition.prototype.and = function(cond) <5>
+SqlCondition.prototype.and = function(pCond) <5>
 {
-    if (!cond)
+    if (!pCond)
         return this;
     if (this._sqlStorage)
         this._sqlStorage += " and ";
-    this._sqlStorage += cond;
+    this._sqlStorage += pCond;
     return this;
 }
 ----
@@ -147,20 +147,22 @@ Add @ignore to the comment of the private functions.
 == 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> jsdoc-blocks have to start with /** because the tool to generate docs out of jsdoc only works with /**
+<3> use the correct form for optional/required parameters: http://usejsdoc.org/tags-param.html
 Optional parameter: [alias=the current alias]
 Required parameter: alias
+Classes: @class
 [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)
+ * @param {String} [pAlias=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) 
+function SqlCondition(pAlias) 
 {
 ...
 }
@@ -171,6 +173,7 @@ function SqlCondition(alias)
 <6> the comments have to start with /** not /* otherwise JSDoc cannot generate a documentation
 
 And how to use it (normally you'd want to use preparedStatements but for the sake of an easy example it's a bit shorter here)
+See also HowToSqlConditionLib.adoc for a full documentation.
 [source,javascript]
 ----
 import("system.vars");
@@ -178,15 +181,13 @@ import("system.result");
 import("Sql_lib");
 import("Comm_lib");
 
-var cond, mediumIds, idVal;
+var cond = new SqlCondition();
 
-cond = new SqlCondition();
-
-mediumIds = CommExtensions.getContextualMediumIds();
+var mediumIds = CommExtensions.getContextualMediumIds();
 if (mediumIds.length > 0)
     cond.and("COMM.MEDIUM_ID in (" + mediumIds.join(", ") + ")");
 
-idVal = vars.get("$local.idvalue");
+var idVal = vars.get("$local.idvalue");
 if (uids.length > 0)
     cond.and("COMM.COMMID = '" + idVal + "' ");
 

others/guide/instanceableLibExample.adoc

@@ -10,49 +10,49 @@ import("...");
 /**
  * instanceable example Utility class;
  * 
- * @param {String} param1 is for ...
+ * @param {String} pParam1 is for ...
  * 
  * @example var myUtil = new UtilClass("-");
  * @class
  */
-function UtilClass(param1) 
+function UtilClass(pParam1) 
 {
     // here is the constructor.
     // create class variables like this:
-    this.myVariable = param1;
+    this.myVariable = pParam1;
 }
 
 /**
  * a public function
  * 
- * @param {String} param1 is for ...
- * @param {String} param2 is for ...
+ * @param {String} pParam1 is for ...
+ * @param {String} pParam2 is for ...
  * 
  * @example var myResult = myUtil.myFunction("p1", "p2");
  * 
  * @return {String} a result
  */
-UtilClass.prototype.myFunction = function(param1, param2) 
+UtilClass.prototype.myFunction = function(pParam1, pParam2) 
 {
-    return this._privateStaticFunction1(param1, param2, this.myVariable);
+    return this._privateStaticFunction1(pParam1, pParam2, this.myVariable);
 }
 
 /**
  * a private function
  * 
- * @param {String} param1 is for ...
- * @param {String} param2 is for ...
- * @param {String} param3 is for ...
+ * @param {String} pParam1 is for ...
+ * @param {String} pParam2 is for ...
+ * @param {String} pParam3 is for ...
  * 
  * @return {String} a result
  * @ignore
  */
-UtilClass.prototype._myPrivateFunction = function(param1, param2, param3) 
+UtilClass.prototype._myPrivateFunction = function(pParam1, pParam2, pParam3) 
 {
-    if(param1 && param2 && param3) 
+    if(pParam1 && pParam2 && pParam3) 
     {
         ...
-        return param1 + param3 + param2;
+        return pParam1 + pParam3 + pParam2;
     }
 
     return "";

others/guide/staticLibExample.adoc

@@ -18,16 +18,16 @@ function ExampleUtils() {} // leave this function empty! A constructor is not ne
 /**
  * a public static function
  * 
- * @param {String} param1 is for ...
- * @param {String} param2 is for ...
+ * @param {String} pParam1 is for ...
+ * @param {String} pParam2 is for ...
  * 
  * @example var myResult = ExampleUtils.staticFunction1("p1", "p2");
  * 
  * @return {String} a result
  */
-ExampleUtils.staticFunction1 = function(param1, param2) 
+ExampleUtils.staticFunction1 = function(pParam1, pParam2) 
 {
-    return this._privateStaticFunction1(param1, param2, "-")
+    return this._privateStaticFunction1(pParam1, pParam2, "-")
 }
 
 /**
@@ -35,19 +35,19 @@ ExampleUtils.staticFunction1 = function(param1, param2)
  * 
  * Do not use outside of ExampleUtils!
  * 
- * @param {String} param1 is for ...
- * @param {String} param2 is for ...
- * @param {String} param3 is for ...
+ * @param {String} pParam1 is for ...
+ * @param {String} pParam2 is for ...
+ * @param {String} pParam3 is for ...
  * 
  * @return {String} a result
  * @ignore
  */
-ExampleUtils._privateStaticFunction1 = function(param1, param2, param3) 
+ExampleUtils._privateStaticFunction1 = function(pParam1, pParam2, pParam3) 
 {
-    if(param1 && param2) 
+    if(pParam1 && pParam2 && pParam3) 
     {
         ...
-        return param1 + param3 + param2;
+        return pParam1 + pParam3 + pParam2;
     }
 
     return "";