[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.

README.md

@@ -1,63 +1,54 @@
 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
 --------
 
-A C# CanOpen EDS (Electronic Data Sheet) library and GUI editor
+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
-CO_OD.c and CO_OD.h) to aid development of CanOpenNode devices.
+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 (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 can open standards
-body CiA.
+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 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.
+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.
+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.
 
-With many thanks to the following contributors for spotting my mistakes and
-improving the code
-	* s-fuchs
-	* martinwag
-	* trojanobelix
-	* many others...
+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
+* 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 CO_OD.c and CO_OD.h
+* 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) *¹
@@ -67,6 +58,10 @@ Library
 *¹ 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.
 
+CLI
+---
+TODO
+
 GUI
 ---
 * Open multiple devices
@@ -77,27 +72,24 @@ GUI
 * 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
+* 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
+* 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.
+* 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
+* 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