Merge pull request #41 from simatic-ax/lint_md

doc: add linter for markdown

.github/workflows/lint.yml

@@ -0,0 +1,19 @@
+name: linter checks
+on:
+  push:
+
+jobs:
+  linter:
+    name: "Linter Checks"
+    runs-on: ubuntu-latest
+
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Check markdown files
+        uses: avto-dev/markdown-lint@v1
+        with:
+          args: '**/*.md'
+          ignore: ./LICENSE.md

.markdownlint.yml

@@ -0,0 +1,11 @@
+# markdownlint YAML configuration
+---
+
+# Default state for all rules
+default: true
+
+# ignored rules
+line-length: false
+no-inline-html: false
+first-line-h1: false
+no-emphasis-as-header: false

LICENSE.md

@@ -1,12 +1,14 @@
+# License
+
 **Royalty-free Software provided by Siemens on sharing platforms for developers/users of Siemens products**
 
-**1. General information: Software in source code and object code**
+## **1. General information: Software in source code and object code**
 
-**1.1 Use of the Software**
+### **1.1 Use of the Software**
 
 Siemens AG and/or a subsidiary of Siemens AG ("Siemens") provides You royalty-free container images, application examples, sample code and software development kits ("Software") through sharing platforms (e.g. GitHub, DockerHub, NuGet, etc.). The Software shall only be used for the development and test of software which can be used with Siemens products ("intended purpose"). The Software is non-binding and makes no claim to completeness or functionality. The Software merely offers help with typical tasks and provides an environment for developing and testing applications and other software. You Yourself are responsible for the proper and safe operation of Your products in accordance with applicable regulations and must also check the function of the results of the Software and customize Your products. Siemens reserves the right to make changes to the Software at any time without notice. Software may be provided in object code and/or source code format. Unless explicitly granted in the open source license according to article 2, You shall not decompile, translate, extract, modify or distribute the Software.
 
-**1.2 Security information**
+### **1.2 Security information**
 
 Siemens provides products and solutions with industrial security functions that support the secure operation of plants, systems, machines and networks.
 
@@ -18,11 +20,11 @@ Customers are responsible for preventing unauthorized access to their plants, sy
 For additional information on industrial security measures that may be implemented, please visit
 <https://www.siemens.com/industrialsecurity>.
 
-**1.3 Compliance with Export Control Regulations**
+### **1.3 Compliance with Export Control Regulations**
 
 You shall comply with all applicable sanctions, embargoes and (re-)export control regulations, and, in any event, with those of the European Union and the United States of America (collectively "Export Regulations"). In particular, the information, software and documentation provided by Siemens (collectively "Licensed Material") shall not be used, accessed or transferred, unless permitted by the Export Regulations or respective governmental licenses or approvals, (i) in or to any location prohibited by or subject to comprehensive sanctions (currently Russia, Cuba, Iran, North Korea, Syria, and the Crimea region of Ukraine, Donetsk and Luhansk regions of Ukraine) or license requirements according to the Export Regulations; (ii) by or to any individual or entity designated on a sanctioned party list of the Export Regulations; (iii) for any purpose prohibited by the Export Regulations (e.g. use in connection with armaments, nuclear technology or weapons); or (iv) to upload any content unless it is noncontrolled (e .g. in the EU: AL = N; in the U.S.: ECCN = N or EAR99). If required to enable authorities or Siemens to conduct export control checks, You, upon request by Siemens, shall promptly provide Siemens with all information pertaining to You, the intended use and the location of use of the Licensed Material. Siemens shall not be obligated to fulfill this Agreement if such fulfillment is prevented by any impediments arising out of national or international foreign trade or customs requirements or any embargoes or other sanctions.
 
-**2. Open Source License for Software in source code and generated source code**
+## **2. Open Source License for Software in source code and generated source code**
 
 In case the Software contains or generates source code the following open source license shall apply for such source code:
 
@@ -36,15 +38,15 @@ The above copyright notice and this permission notice shall be included in all c
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-**3. Software provided in object code**
+## **3. Software provided in object code**
 
 For all portions of the Software that are provided in object code format the following conditions shall apply ("Royalty-Free Siemens Software Conditions"):
 
-**3.1 License Grant**
+### **3.1 License Grant**
 
 Siemens grants You the royalty-free, non-exclusive, non-sublicensable and non-transferable right to use, have used the Software by technically trained personnel and for the intended purpose only.
 
-**3.2 Included third-party software components**
+### **3.2 Included third-party software components**
 
 Insofar as Open Source Software is included in the Software, such Open Source Software is listed in the Readme_OSS file of the Software. You are entitled to use the Open Source Software in accordance with the respective applicable license conditions of the Open Source Software. These OSS license conditions are included with Software and shall prevail over these Royalty-Free Siemens Software Conditions. The Open Source Software license conditions shall have priority also in relation to the proprietary Siemens components insofar as the Open Source Software license conditions grant You certain rights of use on the basis of the connection of OSS components with proprietary Siemens components.
 
@@ -54,7 +56,7 @@ The Software may, in addition to Open Source Software, contain other licensed so
 
 Royalty-Free Software License Version 1.0 – 11.04.2022
 
-**3.3 Disclaimer of liability**
+### **3.3 Disclaimer of liability**
 
 Siemens shall not assume any liability, for any legal reason whatsoever, including, without limitation, liability for the usability, availability, completeness and freedom from defects of the Software as well as for the Licensed Material and any damage caused thereby. This shall not apply in cases of mandatory liability, for example product liability law or in cases of intent, gross negligence, or culpable loss of life, bodily injury or damage to health, non-compliance with a guarantee, fraudulent non-disclosure of a defect, or culpable breach of material contractual obligations. Claims for damages arising from a breach of material contractual obligations shall however be limited to the foreseeable damage typical of the type of agreement, unless liability arises from intent or gross negligence or is based on loss of life, bodily injury or damage to health. The foregoing provisions do not imply any change in the burden of proof to Your detriment. You shall indemnify Siemens against existing or future claims of third parties in this connection except where Siemens is mandatorily liable.
 

README.md

@@ -1,26 +1,31 @@
 # JSON Library
 
 ## Description
+
 This Library will provides the possibility to serialize and deserialize JSON Files.
 
 ## Install this package
 
 Enter:
+
 ```cli
 apax add @simatic-ax/json
 ```
 
-> to install this package you need to login into the GitHub registry. You'll find more information [here](https://github.com/simatic-ax/.sharedstuff/blob/main/doc/personalaccesstoken.md) 
+> to install this package you need to login into the GitHub registry. You'll find more information [here](https://github.com/simatic-ax/.sharedstuff/blob/main/doc/personalaccesstoken.md)
 
 ## Namespace
-```
+
+```sh
 Simatic.Ax.Json;
 ```
 
-# Deserializing
-Use the _Deserializer_ class to deserialize JSON documents and parse values from the document. 
+## Deserializing
+
+Use the _Deserializer_ class to deserialize JSON documents and parse values from the document.
+
+### Restrictions
 
-## Restrictions
 In the current version we have several restrictions regarding the handling of JSON files.
 
 1. The JSON File must be in the form of a ARRAY [] OF CHAR. Read more in the _Workflow_ part.
@@ -54,14 +59,15 @@ In the current version we have several restrictions regarding the handling of JS
 
 ## Workflow
 
-### Pre-requirements.
-1. You need to use the library _Simatic.Ax.Conversion_ and _Simatic.Ax.Json_; 
+### Pre-requirements
+
+1. You need to use the library _Simatic.Ax.Conversion_ and _Simatic.Ax.Json_;
 2. The deserializer currently expects an _ARRAY[0..999] OF CHAR_ as a buffer. If your JSON File is a STRING you can use the _Simatic.Ax.Conversion_ as shown in the example below.
 3. Finally you must set the buffer for the deserializer with the _SetBuffer_ method. The buffer is expected as a reference.
 
 ### Get values
 
-Use the _TryParse_ method to get values that match your provided STRING key . If you want to get values of nested elements you must instead provide a ARRAY [X] OF STRING, with a key for each nested layer. 
+Use the _TryParse_ method to get values that match your provided STRING key . If you want to get values of nested elements you must instead provide a ARRAY [X] OF STRING, with a key for each nested layer.
 
 The datatype _TryParse_ will return depends on the datatype of the value you provide.
 
@@ -124,30 +130,33 @@ parsingWasSuccessfull:= TryParse('not a key', value3);
 |TryParse(input: key (STRING), output: value) : BOOL| Returns false when parsing not succesfull and provides the value. The method is overloaded and accepts different data types. |
 |TryParse(input: key(ARRAY OF STRING), output: value) : BOOL| Returns false when parsing not succesfull and provides the value. The method is overloaded and accepts different data types. The key array is used to access values in nested elements. |
 |||
+
 ### Duplicate keys
 
 The JSON Format allows a user to have duplicate keys in his json document, e.g.
+
 ```JSON
 {
 "key" : "my value",
 "key" : 1234 
 }
 ```
+
 However, the norm does not define, how duplicate keys should be processed. In case of a duplicate key, this library will alwys try to parse the first key and ignore the second one.
 
-# Serializing
+## Serializing
 
 ## [JsonDocument](docs/JsonDocument.md)
 
 ## [JsonObject](docs/JsonObject.md)
 
-# Examples
+## Examples
 
+### Example ho to use the JSON library
 
-## Example ho to use the JSON library
 This example shows in how to create, serialize, parse and reset a JSON document.
 
-```
+```iec-st
 USING Simatic.Ax.Conversion;
 USING Simatic.Ax.Json;
 
@@ -217,7 +226,7 @@ TYPE
 END_TYPE
 ```
 
-## Application Example
+### Application Example
 
 A complete application example, you can find here:
 
@@ -230,4 +239,3 @@ Thanks for your interest in contributing. Anybody is free to report bugs, unclea
 ## License and Legal information
 
 Please read the [Legal information](LICENSE.md)
-

docs/JsonDocument.md

@@ -1,10 +1,11 @@
 # Json Document
 
 ## Description
-The JsonDocument contains the object model of the Json object.
 
+The JsonDocument contains the object model of the Json object.
 
 ## Object
+
 ```mermaid
 classDiagram
 IJsonContainerElement<|--JsonDocument
@@ -24,21 +25,27 @@ JsonDocument : Reset()
 Returns the JSON string of the JSON document (max. 254 characters)
 
 ### Serialize() : BOOL
+
 Serializes the JSON document ino a ARRAY OF CHAR. JsonDocument.buffer must be set before.
 
 ### GetRootElement() : IJsonElement
+
 Returns root element of the JSON document
 
 ### AddElement(elem : IJsonElement)
+
 Add a new element to the JSON document
 
 ### ClearBuffer(hard : BOOL)
+
 Clear the buffer logically (fast). If `hard = TRUE` then delete the buffer also physically (slow) JsonDocument.buffer must be set before.
 
 ### Reset()
+
 Reset the complete object tree and the destination buffer of the JSON document for the purpose, a new JSON object should be created.
 
 ## Example
+
 ```iec-st
 USING Simatic.Ax.Json;
 USING AxUnit.Assert;

docs/JsonObject.md

@@ -1,20 +1,22 @@
 # JsonObject
 
-### Definition
+## Definition
 
 Inheritance: AbstractJsonElement-->JsonObject
 
-### Public members
+## Public members
+
 |||
 |-|-|
 |value : DINT;| Value of this element
 |key : STRING  := 'NoKeySet';| Key of this element
 
-### Methods
+## Methods
+
 |||
 |-|-|
 |ToString() : STRING;| Returns the JSON string of this element|
 |GetRootElement() : IJsonElement| Returns root element of the JSON object|
 |AddElement(elem : IJsonElement)| Add a new element to the JSON object|
 |||
----
+---