[MIX][DOCS] Improving global documentation

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# CANopenEditor Contributing Guidelines
+
+Thank you for your interest in contributing to this project!<br>
+Being a well referenced EDS/DCF editor and the only one supporting CANopenNode, CANopenEditor let everyone manage CANopen files, completely free of charge!<br>
+CANopenEditor is maintained by a small team of volunteers from around the world. As such, those rules are meant for a better communication between everyone but, any help being very welcome, reviewers might approve PRs not respecting all of these rules as long as you tried. Project owners are above those rules as they might have specific needs.<br>
+Please note that by contributing to this project, you agree to have read this file and to the [Developer's Certificate of Origin 1.1](https://developercertificate.org/).
+
+## Discussions
+Discussions shall be done in respect to everyone and everyone's work.
+Any major change shall be first discussed in an issue. Do not worry: maintainers are quite active and will answer.
+
+## Code convention
+This project doesn't really follow any real code convention and doesn't have any linter for now BUT following [common C# code conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) is very welcome and might be asked of you if some parts of your code are too hard to read.
+If linting is ever needed, `dotnet format` will be our solution of choice.
+Even tho there is no hard-defined conventions, non-explicit names or lack of spacing might result in non-approval of a PR.
+
+## What might or might not be a PR
+A simple refactor of code without any real change won't ever be approved. This project relies quite a bit on git blame and as such you are only allowed to refactor code you change. Moreover, trying to enforce a code convention without approval of the main maintainers first might be seen as disrespectful.
+
+## Testing
+Any code change shall be tested. You can:
+- Add unit tests in the right directories
+- Describe any tests you did with the files you might have used
+
+Code that you didn't even try to compile won't be accepted.
+
+## Code comments
+- Complex algorithms MUST be explained with code comments.
+- Hardcoded values (e.g. specific numbers in the middle of nowhere) MUST be justified with code comments.
+- Non explicit data structures (e.g. an array of set size with every index having a meaning) MUST be explained with code comments.
+- Commented lines of code MUST be preceded by a comment line starting with either `//// DEBUG code:` or `//// TODO:`.
+- Comments SHALL have a space between the comment string (e.g. `//`) and the text content.
+- Functions and methods MIGHT have comments describing what they are doing, what are their inputs and/or outputs (if it's not explicit enough).
+- Loops and switches MIGHT have comments justifying why every case is taken into account (if it's not explicit enough).
+- Any more useful comment is welcome.
+
+## Names and descriptions
+### PR names
+They shall be composed of three sections:
+1) Which project is affected (MIX if multiple)
+2) What types of changes are made (e.g. FEAT, FIX, DOCUMENTATION/DOC, CORRECTION/CORR, SUGGESTION/SUGG, BUILD, ...)
+3) An explicit but less than 100 chars long summary of the changes
+
+Sections shall be clearly separated (e.g. with colons, parenthesis, ...).<br>
+Examples of valid and explicit PR names: `[MIX][DOC] Explaining explicit PR title rules`, `gui2: fix: Fixed bug where 1 = 2`.<br>
+If you have multiple unrelated changes (e.g. adding a feature and fixing another) to do, please do multiple PRs.
+
+### PR descriptions
+They shall:
+- Describe any change made
+- Explain why such changes are made
+- Explain any decision taken
+- Link any related issue / any related other PR
+- Describe any test made
+- The sentence "I have read the contributing guidelines, I agree to following them and I agree to the Developer's Certificate of Origin 1.1"
+
+### Commits
+Names shall be composed of:
+1) What types of changes are made (e.g. PR names sections 2)
+2) An explicit but less than 100 chars long summary of the changes
+
+Descriptions are entirely up to you.

EDSEditorGUI/README.md

@@ -0,0 +1,22 @@
+GUI
+=============
+* Open multiple devices
+* Open EDS/DCF/XDC files
+* Save EDS/DCF/XDC files
+* View OD Entries and explore the Object Dictionary
+* Add new OD entries
+* Delete exisiting OD entries
+* Create new Devices
+* Add default profiles
+* Create profiles that can be added to any project (just save the device xml file to the profiles/ directory, only include the minimum number of objects that you want to auto insert); This will auto add to insert menu
+* Edit Device and File Info sections
+* Set RX/TX PDO mappings easily from dropdown lists of available objects
+* Add and remove new PDO entries (communication paramaters and mapping) with a single button's push
+* Save groups of EDS/XML files as a network object with ability to set concrete node IDs
+* View report of all configured PDOs across the network
+* View modules and module details present within EDS files
+* View/edit actual object values for device configuring/DCF files
+* Support for loading XDD files (CanOpen offical XML)
+* Support for saving XDD files (CanOpen offical XML)
+* Some module info is displayed in GUI showing available modules (eds) and configured modules (dcf) and what OD entries they reference.
+  Full details such as subobj extension and fixed subobj are not currently displayed and unless there is demand probably will not ever be.

EDSEditorGUI2/README.md

@@ -0,0 +1,3 @@
+GUI2
+=============
+This GUI is meant to be cross-platform, meant to replace the old GUI and is made using Avalonia. It is not yet ready.

EDSSharp/README.md

@@ -0,0 +1,54 @@
+EDSSharp
+=============
+
+A C# CanOpen EDS (Electronic Data Sheet) library, CLI convertor and GUI editor.
+
+This application is designed to load/save/edit and create EDS/DCF/XDC file for CANopen and also to generate the object dictionary for CANopenNode (V1.3 and newer) to aid development of CANopenNode devices.
+
+EDS (Electronic Data Sheet) files are text files that define CANopen devices.
+DCF (Device Configuration File) files are text files that define configured CANopen devices.
+XDD files are an XML version of EDS files.
+
+EDS/DCF are fully defined in the DSP306 standard by the CANopen standards body: CiA.
+
+The EDS editor on its own is useful without the CANopenNode specific export and, as of the 0.6-XDD-alpha version, the editor can also load/save XDD files.
+The GUI also shows PDO mappings and can generate reports of multiple devices that are loaded into the software.
+
+The core library can be used without the GUI to implement eds/xdd loading/saving and parsing etc in other projects.
+
+Please consider this code experimental and beta quality.
+It is a work in progress and is rapidly changing.
+
+Every attempt has been made to comply with the relevant DSP306 and other standards and EDS files from multiple sources have been tested for loading/saving and as been (at times) validated for errors using EDS conformance tools.
+
+Usage
+-----
+- Using `dotnet run`, your {name} is `dotnet run EDSSharp/Program.cs --project EDSSharp --framework [net481/net8.0]`.
+- Using compiled version, your {name} is the name of your executable.
+- Depending on your environment, you may or may not need to use ./ at the beginning of your command
+
+`{name} --infile FILE1 --outfile FILE2 [--type EXPORTER]`<br>
+Converts a given XDD or EDS file to many other available types.<br>
+Example: {name} --infile project.xdd --outfile map.md --type NetworkPDOReport<br>
+<br>
+FILE1 shall be a .xdd or .eds file.<br>
+FILE2 shall have the extension of one of the supported exporters below.<br>
+EXPORTER shall be one of the listed exporters below IF AND ONLY IF multiple of them support your output file extension.<br>
+<br>
+Available exporters for now:<br>
+- ElectronicDataSheet [.eds]
+- DeviceConfigurationFile [.dcf]
+- CanOpenNode [.h,.c]
+- CanOpenNodeV4 [.h,.c]
+- CanOpenXDDv1.0 [.xdd]
+- CanOpenNetworkv1.0 [.nxdd]
+- CanOpenXDDv1.1 [.xdd]
+- CanOpenXDDv1.1stripped [.xdd]
+- CanOpenXDCv1.1 [.xdc]
+- CanOpenNetworkXDDv1.1 [.nxdd]
+- CanOpenNetworkXDCv1.1 [.nxdc]
+- CanOpenNodeProtobuf(json) [.json]
+- CanOpenNodeProtobuf(binary) [.binpb]
+- DocumentationHTML [.html]
+- DocumentationMarkup [.md]
+- NetworkPDOReport [.md]

GUITests/README.md

@@ -0,0 +1,3 @@
+GUITests
+=============
+This directory only contains unit tests for the old GUI for now. More tests, functional tests or tests for the new GUI might be added later. All tests shall be written is C# and executable on Windows.

Images/README.md

@@ -0,0 +1,9 @@
+Images
+=============
+Contains any and all images used in the documentation. Not all images in here are used but no image used in the documentation shall be anywhere but here.
+
+Here are some:
+![Device info section of the GUI](pic2.jpg)
+![OD section of the GUI](pic1.jpg)
+![TX PDO Mapping section of the GUI](pic3.jpg)
+![A specific PDO view in the GUI](pic4.jpg)

README.md

@@ -1,121 +1,37 @@
 CANopenEditor
 =============
-CANopenEditor is a fork from https://github.com/robincornelius/libedssharp, author Robin Cornelius.
-Its homepage is https://github.com/CANopenNode/CANopenEditor
+CANopenEditor is a fork from [libedssharp, authored by Robin Cornelius](https://github.com/robincornelius/libedssharp).
+CANopenEditor's homepage is https://github.com/CANopenNode/CANopenEditor.
 
 CANopen Object Dictionary Editor:
  - Imports: CANopen electronic data sheets in EDS or XDD format.
- - Exports: CANopen electronic data sheets in EDS or XDD format, documentation, CANopenNode C source files.
- - GUI editor for CANopen Object Dictionary, Device information, etc.
+ - Exports: CANopen electronic data sheets in EDS or XDD format, documentation, CANopenNode C source files and more.
+ - Interfaces: GUI editor for CANopen Object Dictionary, Device information, etc. CLI client for simple conversions.
 
-CANopen is the internationally standardized (EN 50325-4) ([CiA301](http://can-cia.org/standardization/technical-documents)) higher-layer protocol for embedded control system built on top of CAN. For more information on CANopen see http://www.can-cia.org/
+CANopen is the internationally standardized (EN 50325-4) ([CiA301](http://can-cia.org/standardization/technical-documents)) higher-layer protocol for embedded control system built on top of CAN. For more information on CANopen see http://www.can-cia.org/ .
 
-[CANopenNode](https://github.com/CANopenNode/CANopenNode) is free and open source CANopen Stack
+[CANopenNode](https://github.com/CANopenNode/CANopenNode) is a free and open source CANopen Stack.
 
-
-EDSSharp
+File structure
 --------
-
-A C# CanOpen EDS (Electronic Data Sheet) library and GUI editor
-
-This application is designed to load/save/edit and create EDS/DCF/XDC file for
-CanOpen and also to generate the object dictionary for CanOpenNode
-CO_OD.c and CO_OD.h) to aid development of CanOpenNode devices.
-
-EDS (Electronic Data Sheet) files are text files that define CanOpen Devices.
-DCF (Device Configuration File) files are text files that define configured
-CanOpenDevices XDD files are an XML version of EDS files
-
-EDS/DCF are fully defined in the DSP306 standard by the can open standards
-body CiA.
-
-The EDS editor on its own is useful without the CanOpenNode specific export and
-as of the 0.6-XDD-alpha version the editor can also load/save XDD files.
-The GUI also shows PDO mappings and can generate reports
-of multiple devices that are loaded into the software.
-
-The core library can be used without the GUI to implement eds/xdd loading/saving
-and parsing etc in other projects.
-
-Please consider this code experimental and beta quality.
-It is a work in progress and is rapidly changing.
-
-Every attempt has been made to comply with the revelant DSP306 and other
-standards and EDS files from multiple sources have been tested for loading and
-saving as been (at times) validated for errors using EDS conformance tools.
-
-With many thanks to the following contributors for spotting my mistakes and
-improving the code
-	* s-fuchs
-	* martinwag
-	* trojanobelix
-	* many others...
-
-Library
--------
-
-* Read EDS/DCF/XDC file and parse contents to approprate classes
-* Dump EDS/DCF classes via ToString()
-* Save EDS/DCF classes back to EDS file
-* Export C and H files in CanOpenNode format CO_OD.c and CO_OD.h
-* EDS/DCF supports modules
-* EDS/DCF supports compactPDO (read only) *¹
-* EDS/DCF supports implict PDO (read only) *¹
-* EDS/DCF supports CompactSubOb (read only) *¹
-* Supports loading/saving of all EDS/DCF module information
-
-*¹ Read only, in this context, means the EDS/DCF is fully expanded but the compact
-   forms is not written back, only the expanded form will be saved.
-
-GUI
----
-* Open multiple devices
-* Open EDS/DCF/XDC files
-* Save EDS/DCF/XDC files
-* View OD Entries and explore the Object Dictionary
-* Add new OD entries
-* Delete exisiting OD entries
-* Create new Devices
-* Add default profiles
-* Create profiles that can be added to any project (just save the device xml file to the profiles/
-  directory, only include the minimum number of objects that you want to auto insert) This will auto add to insert menu
-* Edit Device and File Info sections
-* Set RX/TX PDO mappings easily from dropdown lists of available objects
-* Add and remove new PDO entries (communication paramaters and mapping) in a single button push
-* Save groups of EDS/XML files as a network object with ability to set concrete node IDs
-* View report of all configured PDOs across the network
-* View modules and module details present within EDS files
-* View/edit actual object values for device configuring/DCF files
-* Support for loading XDD files (CanOpen offical XML)
-* Support for saving XDD files (CanOpen offical XML)
-* Some module info is displayed in GUI showing available modules (eds) and
-  configured modules (dcf) and what OD entries they reference. Full details such
-  as subobj extension and fixed subobj are not currently displayed and unless
-  there is demand probably will not ever be.
-
-TODO
-----
-
-* Ensure and validate all XDD is loading/save correctly (Looking good so far)
-* Add extra Gui fields for accessing extra XDD paramaters not in EDS
-  (all common ones are done, a few special/edge cases remain)
-* Look at XDC files and see if we can save config changes and allow editing and
-  network setup here in the app, partial support is implemented by supporting
-  DCF files
-
+The main files and directories you'll need to understand are:
+- [setup.nsi](https://github.com/CANopenNode/CANopenEditor/blob/main/setup.nsi) is the Windows installer.
+- [Makefile](https://github.com/CANopenNode/CANopenEditor/blob/main/Makefile) is the Linux installation and manipulation script.
+- [EDSEditorGUI](https://github.com/CANopenNode/CANopenEditor/tree/main/EDSEditorGUI) directory is the old GUI. Fully functional but only works on Windows.
+- [EDSEditorGUI2](https://github.com/CANopenNode/CANopenEditor/tree/main/EDSEditorGUI2) directory is the new GUI. It is not fully finished yet but is meant to work on any Windows, Mac or Linux OS.
+- [EDSSharp](https://github.com/CANopenNode/CANopenEditor/tree/main/EDSSharp) directory is the CLI. It is only meant for simple conversions for now.
+- [GUITests](https://github.com/CANopenNode/CANopenEditor/tree/main/GUITests) directory is the directory for all GUI unit tests. More tests, functional tests and tests for GUI2 may come here.
+- [Images](https://github.com/CANopenNode/CANopenEditor/tree/main/Images) directory is the directory containing any and all of the documentation's images.
+- [Tests](https://github.com/CANopenNode/CANopenEditor/tree/main/Tests) directory is the directory for all Lib unit tests. More tests, functional tests and tests for CLI may come here.
+- [libEDSsharp](https://github.com/CANopenNode/CANopenEditor/tree/main/libEDSsharp) directory contains the libe from Robin Cornelius making all of this work.
 
 BUGS
-----
+--------
 
-If you find any, please open a bug report on github and attach any files you
-have created/opened etc.
+If you find any, please open a bug report on github and attach any files you have created/opened etc... We need any help we can have and the main maintainers are quite active and will answer you fast.
 
 You might want to check your EDS/XDD file with this free [EDSchecker](https://www.vector.com/de/de/support-downloads/download-center/#product=%5B%2274771%22%5D&tab=1&pageSize=15&sort=date&order=desc)
 
-Pictures
+Contributing
 --------
-
-![alt tag](pic1.jpg)
-![alt tag](pic2.jpg)
-![alt tag](pic3.jpg)
-![alt tag](pic4.jpg)
+If you want to help us out by contributing to this project, first of all thank you ! And please read our [Contributing Guidelines](https://github.com/CANopenNode/CANopenEditor/blob/docs/CONTRIBUTING.md). We are very beginner friendly so, even if you are not extremely experienced with contributing to open source projects, fear not and try !

Tests/README.md

@@ -0,0 +1,3 @@
+Tests
+=============
+This directory only contains unit tests for the lib for now. More tests, functional tests or tests for the CLI might be added later. All tests shall be written is C# and executable on Windows.

libEDSsharp/README.md

@@ -0,0 +1,15 @@
+libEDSsharp
+=============
+The library making it all work.
+
+* Read EDS/DCF/XDC file and parse contents to appropriate classes
+* Dump EDS/DCF classes via ToString()
+* Save EDS/DCF classes back to EDS file
+* Export C and H files in CANopenNode format (V1.3 and newer)
+* EDS/DCF supports modules
+* EDS/DCF supports compactPDO (read only) \*¹
+* EDS/DCF supports implict PDO (read only) \*¹
+* EDS/DCF supports CompactSubOb (read only) \*¹
+* Supports loading/saving of all EDS/DCF module information
+
+\*¹ Read only, in this context, means the EDS/DCF is fully expanded but the compact forms is not written back, only the expanded form will be saved.