@intelligentgraphics/ig.gfx.packager 3.0.4 → 3.0.5

package/readme.md

@@ -294,35 +294,89 @@ The path specified after the media:// schema will be resolved within a directory
 
 ### \_Index.json generation
 
-The packager has a cli command `generateIndex [directory]`, it will generate an \_Index.json file for Evaluator packages.
-The ts files have to adhere to a certain form to be processed.
-
-1. The namespace/module name has to have two parts like: `namespace IG.Test`
-2. The evaluator class has to extend the base evaluator class IEvaluator from IGX.Eval
-3. The parameters have the following JSDoc structure
-    ```javascript
-    /** Symbolische Angabe der Korpusbreite in der Form "W100"
-     * Wird in der abgeleitet Klasse kontextbezogen in den Realwert Width gemapped.
-     * @default "W50"
-     * @creatorType String
-     * @summary Symbolische Angabe der Korpusbreite
-     */
-    Corpus_Width: string;
-    ```
-    which results in the following
-    ```
-    {
-        "Name": "Corpus_Width",
-        "Description": "Symbolische Angabe der Korpusbreite",
-        "Type": "String",
-        "Default": "W50",
-        "DisplayIndex": 1
-    }
-    ```
-4. `DisplayIndex` is generated from the order of the parameters
-5. Jsdoc for the Evaluator has to be above class
-6. Parameter and Package name length need to be <=45
-7. Description is cut off after 99 characters
+The packager has a cli command `npm run generateIndex [directory]` to generate an \_Index.json file for an Evaluator package.
+
+You may need to register this command in the package.json of your git repository by adding the following attribute to the scripts object:
+
+```json
+"scripts": {
+   "generateIndex": "packager generateIndex"
+},
+```
+
+This command collects all classes that either implement or extend the IEvaluator class from IGX.Eval, collects the properties of their parameters
+and generates the \_Index.json file based on JSDoc informations for the properties and the class.
+
+The following jsdoc attributes are supported:
+
+-   _default_ -> the default value
+-   _creatorType_ -> to define the type (like Material, String, Geometry)
+-   _summary_ -> to set a short description for the parameter. By default the generator will use the text above the attributes as the description.
+
+**Example:**
+
+```ts
+namespace IG.Test {
+	interface Params {
+		/**
+		 * Width of the corpus.
+		 *
+		 * Additional informations used to document the property internally
+		 *
+		 * @default 1.0
+		 * @creatorType Float
+		 * @summary Width of the corpus
+		 */
+		Corpus_Width?: number | string;
+
+		/**
+		 * Type of the corpus
+		 *
+		 * @default "extra_wide"
+		 * @creatorType String
+		 */
+		Corpus_Type?: string;
+	}
+
+	/**
+	 * The description of my evaluator
+	 */
+	export class MyEvaluator extends IGX.IEvaluator {
+		public static Create(
+			productId: string,
+			path: string,
+			parameters: Params,
+		): IGX.EvalResponse {}
+	}
+}
+```
+
+The code snippet above will generate the following \_Index.json output:
+
+```json
+[
+	{
+		"Name": "IG.Test.MyEvaluator",
+		"Description": "The description of my evaluator",
+		"Type": "Evaluator",
+		"Parameters": [
+			{
+				"Name": "Corpus_Width",
+				"Description": "Symbolische Angabe der Korpusbreite",
+				"Default": "W50",
+				"Type": "String",
+				"DisplayIndex": 1
+			}
+		]
+	}
+]
+```
+
+**Migrating from a handwritten \_Index.json to an auto generated one:**
+
+1. Make sure all Evaluators implement or extend the IGX.IEvaluator class.
+2. Run the index generation. The output should be nearly identical. If an evaluator does not have an explicit Parameter type, the generator will reuse the informations from an existing \_Index.json file.
+3. Now you can choose to add the parameter types either incrementally or all at once.
 
 ## Troubleshoot
 
@@ -333,6 +387,14 @@ Afterwards you may need to reload your editor in order for the installed files t
 
 ## History
 
+**IG.GFX.Packager 3.0.5**
+
+-   update documentation for generateIndex command
+-   enforce better property order for parameters
+-   improve index generation
+-   use typechecker for index generation to improve reliability
+-   reuse parameters of existing \_index.json when no parameters are defined for an evaluator
+
 **IG.GFX.Packager 3.0.4**
 
 -   start a troubleshoot section