From fc778c76c2a6264e5ac9a3bcf33dce2375ee26b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Breitbart?= <jerch@rockborn.de>
Date: Tue, 18 Jun 2019 15:23:36 +0200
Subject: [PATCH] add usage example for action handler

---
 src/common/parser/Params.ts | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/common/parser/Params.ts b/src/common/parser/Params.ts
index 74cd5a79..27b180da 100644
--- a/src/common/parser/Params.ts
+++ b/src/common/parser/Params.ts
@@ -8,9 +8,31 @@ import { IParams } from 'common/parser/Types';
  * Params storage class.
  * This type is used by the parser to acuumulate sequence parameters and sub parameters
  * and transmit them to the input handler actions.
- * Note: The params object for the handler actions is borrowed from the parser
- * and will be lost after the handler exits. Use either `toArray` or `clone` to get
- * a stable copy of the data.
+ *
+ * Usage in action handler:
+ *   ```typescript
+ *   function handler(params: IParams): void {
+ *     for (let i = 0; i < params.length; ++i) {
+ *       // get single param
+ *       const param = params.params[i];
+ *       ...
+ *       // check for sub params
+ *       if (Params.hasSubParams(i)) {
+ *          // get sub params
+ *          const subparams = params.getSubParams(i);
+ *          ...
+ *       }
+ *     }
+ *   }
+ *   ```
+ *
+ * NOTES:
+ *  - params object for action handlers is borrowed, use `.toArray` or `.clone` to get a copy
+ *  - never read beyond `params.length - 1` (likely to contain arbitrary data)
+ *  - `.getSubParams` returns a borrowed typed array, use `.getSubParamsAll` for cloned sub params
+ *  - hardcoded limitations:
+ *    - max. value for a single (sub) param is 2^15 (caveat: will overflow to negative values)
+ *    - max. 256 sub params possible
  */
 export class Params implements IParams {
   // params store and length