Updated the documentation

Author: joergschultzelutter

docs/USAGE.md

@@ -13,7 +13,9 @@ The following input parameter are supported:
 ## Known issues and constraints
 
 - The ``Send API Request``  command used in the program's template files is not present as a keyword and acts as a mere placeholder; __you need to amend this section in the program's template files__. See [Configuration documentation](CONFIGURATION.md)
-- If your OpenAPI file contains information on the API's URL, the program tries to extract that content from the file and replace a placeholder in the future ``includes.resource`` file. If an URL could not be retrieved, you need to manually replace that placeholder.
+- For each API call, the program tries to extract the desired HTTP response code from the API description whereas present in the OpenAPI file. As there is no real classification on 'good' and 'bad' return codes, the program will nominate the very first HTTP response code as desired response code. Usually, this is the one that we want - but your miles may vary.
+- OpenAPI services without an ``operationId`` will raise an error as this is the generator's identifying element for the test case names. See "How does this program work" for more details on this issue.
+- If your OpenAPI file contains information on the API's URL, the program will try to extract that content from the file and replace a placeholder in the future ``includes.resource`` file. If an URL could not be retrieved, you need to manually replace that placeholder. You may need to amend the associated regex in the Python code.
 - The OpenAPI parser is VERY sensitive if you try to parse an OpenAPI file which deviates from the OpenAPI standards but may be accepted by other systems and software. The ``openapi-spec-validator`` [uses strict mode](https://github.com/RonnyPfannschmidt/prance#compatibility), meaning that e.g. no integer-based keys in the OpenAPI spec file are allowed. If the program crashes, then an error like this might be the reason.
 - The Robot demo code (not the actual parser itself) cannot deal with multi-layered JSON request bodies in an automated manner. The current approach focuses on fields on a single layer
 
@@ -36,12 +38,13 @@ Example:
       }
     }
 
-This does _not_ mean that you cannot use the program for the initial test generation - the program will still be able to extract all fields from the OpenAPI file, add them to the Excel file and generate the Robot code for you. However, nested structures are not automatically generated and you may be forced to apply some additional changes to the code in order to create a nested JSON object.
+This does _not_ mean that you cannot use the program for the initial test generation - the program will still be able to extract all fields from the OpenAPI file, add them to the Excel file and generate the Robot code for you. However, nested structures are not automatically generated but rather reflected as flat structures, thus potentially forcing you to apply some additional changes to the code in order to create a nested JSON object.
 
 - Robot Framework test case names need to be unique. As there is a remote chance that an OpenAPI file _may_ contain test names which could result in dupes, the program tries to dodge these edge cases by forming a combination of the API call's internal name AND the HTTP method. This approach works for me but your miles may vary.
 
 - The sample code assumes that your [robotframework-datadriver](https://github.com/Snooz82/robotframework-datadriver) version is 1.5.0 or later - which will be installed by default (but is not required by the actual generator itself). The Robot Framework demo template that comes with this repo makes _heavy_ usage of the Datadriver's [typed cells](https://github.com/Snooz82/robotframework-datadriver#ms-excel-and-typed-cells) option, meaning that you apply the desired target format for your input data directly to your respective Excel cell. For example, a cell containing the numeric value of 123 with an Excel _General_ format will be recognised as Integer value whereas the same value with an Excel _Text_ formatting will be treated as text. Booleans, Floats etc are supported. Some edge cases may not work out of the box and may require some manual magic, though.
-- If you use the Jira ticket generator option, be advised that for each run of the program, __new__ tickets will be generated.
+    - For convenience purposes, the Robot Framework template code ensures that you run the correct version of the Robot Framework datadriver in order to avoid any future data misinterpretation.
+- If you use the Jira ticket generator option, be advised that for each run of the program, __new__ tickets will be generated __WITH EACH PROGRAM RUN__.
 
 ## How does this program work?