Documentation/interface convention

doc/commenting.rst

@@ -215,14 +215,22 @@ Every OSI message should be defined properly and should have a well cited refere
 - Find filled-out examples under `https://apastyle.apa.org <https://apastyle.apa.org/style-grammar-guidelines/references/examples>`_ and in existing entries.
 - The scheme of popular sources for the reference list is as follows (replace tags with corresponding values):
 
-.. [#] <author1>, <author2>, <author3> & <author4>. (<year>). Contribution in a compilation title. <em><Compilation Title></em>. <edition>. <page(s)>. <publisher>. <location>. <doi>. <page(s)>.
-.. [#] <author1>, <author2> & <author3>. (<year>). <em><book (monograph) title></em>. <edition>. <publisher>. <doi>. <page(s)>.
-.. [#] <author1> & <author2>. (<year>). <book chapter title>. In <editor1> & <editor2> (Eds.), <em><book title></em> (<page(s)>). <publisher>. <doi>. <page(s)>.
-.. [#] <author1> & <author2>. (<year>). <journal article title>. <em><journal title></em>. <page(s)>. <location>. <doi>. <page(s)>.
-.. [#] <author>. (<year>). <em><Phd thesis title></em>. Phd. thesis. <location>. <university>. <doi or url>. <page(s)>.
-.. [#] <author>. (<year>, <month> <day>). <em><internet article title></em>. Retrieved <month> <day>, <year>, from <url>.
-.. [#] <standarding organisation>. (<year>). <em><title of the standard></em>. (<standard identifier>). <location>.
-.. [#] <author>. (<year>). <em><patent title and id></em>. <location>. <organisation>.
+1. <author1>, <author2>, <author3> & <author4>. (<year>). Contribution in a compilation title. <em><Compilation Title></em>. <edition>. <page(s)>. <publisher>. <location>. <doi>. <page(s)>.
+
+2. <author1>, <author2> & <author3>. (<year>). <em><book (monograph) title></em>. <edition>. <publisher>. <doi>. <page(s)>.
+
+3. <author1> & <author2>. (<year>). <book chapter title>. In <editor1> & <editor2> (Eds.), <em><book title></em> (<page(s)>). <publisher>. <doi>. <page(s)>.
+
+4. <author1> & <author2>. (<year>). <journal article title>. <em><journal title></em>. <page(s)>. <location>. <doi>. <page(s)>.
+
+5. <author>. (<year>). <em><Phd thesis title></em>. Phd. thesis. <location>. <university>. <doi or url>. <page(s)>.
+
+6. <author>. (<year>, <month> <day>). <em><internet article title></em>. Retrieved <month> <day>, <year>, from <url>.
+
+7. <standarding organisation>. (<year>). <em><title of the standard></em>. (<standard identifier>). <location>.
+
+8. <author>. (<year>). <em><patent title and id></em>. <location>. <organisation>.
+
 
 
 .. code-block:: protobuf

doc/interfaceconventions.rst

@@ -0,0 +1,76 @@
+.. _iconventions:
+
+Interface Conventions
+======================
+
+When adding new messages, enums, field messages and field enums to OSI we enforce a few naming conventions for each type like in the `style guide <https://developers.google.com/protocol-buffers/docs/style>`_ from protobuf.
+
+Message Naming
+---------------
+A message definition should always be in camel case. This means that the first letter of each word in a message should be upper case without any spaces. See example below:
+
+.. code-block:: protobuf
+
+    message EnvironmentalConditions
+    {
+    }
+
+Field Message Naming
+---------------------
+After defining a message custom fields can be added to it in snake case format. This means every letter is lower case and the words are connected through an underline character. See example below:
+
+.. code-block:: protobuf
+
+    message EnvironmentalConditions
+    {
+        optional double atmospheric_pressure = 1;
+    }
+
+Enum Naming
+------------
+The naming of an enum should be camel case. See example below:
+
+.. code-block:: protobuf
+
+    message EnvironmentalConditions
+    {
+        optional double atmospheric_pressure = 1;
+
+        enum AmbientIllumination
+        {
+        }
+    }
+
+Enum Field Naming
+------------
+The naming of an enum field should be all in upper case. The start should be converted from the enum name camel case to upper case snake case. It is mandatory to have as a first enum field name the name ``_UNKNOWN`` and as the second the name ``_OTHER`` attached to it. After that the naming can be decided by the user. See example below:
+
+.. code-block:: protobuf
+
+    message EnvironmentalConditions
+    {
+        optional double atmospheric_pressure = 1;
+
+        enum AmbientIllumination
+        {
+            AMBIENT_ILLUMINATION_UNKNOWN = 0;
+
+            AMBIENT_ILLUMINATION_OTHER = 1;
+
+            AMBIENT_ILLUMINATION_LEVEL1 = 2;
+        }
+    }
+
+Summary
+--------
+Here a small summary for the naming conventions:
+
+Messages: camel case
+
+Message Fields: snake case
+
+Enum: camel case
+
+Enum Fields: upper case, name of enum converted in upper case snake case and then following the specified name
+
+After defining the messages do not forget to comment them. See also the `section for commenting <https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/commenting.html>`_ of fields and messages.