update documentation

see ehrbase/project_management#424

README.md

@@ -1,31 +1,50 @@
-# EHRBase SDK  
+# EHRBase SDK
+
 ## client (mostly Beta)
+
 Generic openEHR Client and Objekt-mapper:
+
 * Define entity classes for openEHR-Templates (v1.4) in a jpa like way
 * Map entity <-> Archie RM objekts.
-* RestClient for openEHR Rest-API 
+* RestClient for openEHR Rest-API
 * AQL-Query generator (Alpha)
+
 ## generator (Beta)
-* Autogenerate  entity classes from template
+
+* Autogenerate entity classes from template
+
 ## opt-1.4 (Beta)
+
 * Opt 1.4 xmlbeans
+
 ## response-dto (Beta)
+
 * DTO's representing the response for the ehrsacpe and openEHR Rest API
+
 ## terminologie (Beta)
+
 * Mini openEHR terminologie implementation
+
 ## validation (Beta)
+
 * Validation of Compositions against templates
+
 ## test-data (Beta)
+
 * Example templates and Composition for tests
+
 ## serialisation (Beta)
+
 * map Compositions from and to JSON;XML
 
 ## Release Notes (v0.3.6)
+
 * CircleCI pipeline w/ Jacoco code coverage and sonarcloud.io analysis
 * semi automated version updating via [major] / [minor] / [patch] flags in merge commit title of Github PR
 * updated test dependencies to use Junit5
 
 ## Release Notes (v0.3.0)
+
 * RestClient for DIRECTORY endpoint
 * Improved clean-up of empty elements
 * Improved generation of EVENT classes
@@ -36,36 +55,57 @@ Generic openEHR Client and Objekt-mapper:
 ## Installation
 
 ### Build
+
 ```bash
 mvn clean install
 ```
 
 ## Usage
-###  Entity generation
+
+### Entity generation
+
 To generate an entity class from a template use
+
 ```bash
  java  -jar generator-version.jar
  -h               show help
  -opt <arg>       path to opt file
  -out <arg>       path to output directory
  -package <arg>   package name
+ -config <arg>    optional Path to config file
 ```
+
+In the optional config file you can define
+
+Parameter        | Default                         | Description
+ -----------     | ---------                       | ------------- 
+optimizerSetting | SECTION                         | Defines if nodes which belong to are archetype but are single valued generate a new class: <ul><li>NONE: Always generate a class for nodes which belong to a archetype</li><li>SECTION: Do not generate a class for nodes which have rm-type section and are single valued</li><li>ALL: Do not generate a class for nodes which are single valued</li></ul>
+addNullFlavor    | true                            | Whether or not to generate null flavor fields for Elements.
+replaceChars     | German and Norwegian Characters | Map to define Characters in the Node name to be replaced. 
+
+see generator/src/main/resources/DefaultConfig.yaml
+
 ### Use The SDK in your projekt
+
 You can include the SDK via [jitpack.io](https://jitpack.io/#ehrbase/openEHR_SDK)
-####  Map entity <-> Archie RM objekts
+
+#### Map entity <-> Archie RM objekts
 
 see FlattenerTest and UnflattenerTest
 
-#### RestClient for openEHR Rest-API 
+#### RestClient for openEHR Rest-API
 
 - ehr : see DefaultRestEhrEndpointIT
 - composition: see DefaultRestCompositionEndpointIT
 - template : see DefaultRestTemplateEndpointIT
 - directory : see DefaultRestDirectoryEndpointIT
+
 ## Contributing
+
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 
 Please make sure to update tests as appropriate.
 
 ## License
+
 [APACHE 2.0](https://www.apache.org/licenses/LICENSE-2.0)

UPDATING.md

@@ -0,0 +1,23 @@
+# Updating the SDK
+
+This file documents any backwards-incompatible changes in SDK and
+assists users migrating to a new version.
+
+## SDK 1.0.0
+### Using the sdk with old generated classes
+Classes generated with the old SDK can be used with the new version
+### Migrating from old generated classes to new ones
+It is recommended to update the generated classes. To do this:
+* Update the sdk version
+* Rename any Name with *defningcode to *defningCode
+* replace the EnumValueSet in your local shareddefinition folder with the new from the sdk:
+  * Language -> org.ehrbase.client.classgenerator.shareddefinition.Language
+  * CategoryDefiningcode -> org.ehrbase.client.classgenerator.shareddefinition.Category
+  * MathFunctionDefiningcode -> org.ehrbase.client.classgenerator.shareddefinition.MathFunction
+  * SettingDefiningcode -> org.ehrbase.client.classgenerator.shareddefinition.Setting
+  * Territory -> org.ehrbase.client.classgenerator.shareddefinition.Territory
+  * TransitionDefiningcode ->  org.ehrbase.client.classgenerator.shareddefinition.Transition
+
+* Generate your classes new with the generator using generator/src/main/resources/LegacyConfig.yaml as config
+* Delete you old classes and replaces them with the new one
+* There may be some more changes regrading the naming or the class structure which you have to change in your code.

generator/src/main/java/org/ehrbase/client/classgenerator/ClassGeneratorConfig.java

@@ -24,10 +24,13 @@
 
 public class ClassGeneratorConfig {
 
+  /** Defines if nodes which belong to are archetype but are single valued generate a new class. */
   private OptimizerSetting optimizerSetting = OptimizerSetting.NONE;
+  /** Whether or not to generate null flavor fields for Elements. */
   private boolean addNullFlavor = false;
 
-  private final Map<Character,String>  replaceChars = new HashMap<>();
+  /** Map to define Characters in the Node name to be replaced. */
+  private final Map<Character, String> replaceChars = new HashMap<>();
 
   public OptimizerSetting getOptimizerSetting() {
     return optimizerSetting;

generator/src/main/java/org/ehrbase/client/classgenerator/OptimizerSetting.java

@@ -20,7 +20,10 @@
 package org.ehrbase.client.classgenerator;
 
 public enum OptimizerSetting {
+  /** Always generate a class for nodes which belong to a archetype */
   NONE,
+  /** Do not generate a class for nodes which have rm-type section and are single valued */
   SECTION,
+  /** Do not generate a class for nodes which are single valued */
   ALL;
 }