docs: Update docs regarding comments

docs/source/messages.rst

@@ -54,13 +54,12 @@ Class Definition
 Enum definition
 ===============
 * A `.msg` file can contain multiple enum definitions.
-* Multiple enum definitions are separated by an empty line.
-* Enum names are determined based on the longest common prefix of all enum literals in the enum definition.
+* Enum names are determined based on the common prefix of all enum literals in the enum definition.
 * If no common prefix exists, the enum name is derived from the file name (excluding the extension).
 * Two or more enums must not have literal names without a common prefix.
 * **Inline Comments:** Comments on the same line as an enum literal definition are directly added to the that enum literal's description.
 * **Indented Comment Lines:** Comments on a line of their own but indented are added to the description of the last encountered enum literal.
-* **Block Comments:** Comments on a line of their own and not indented are added to the description of the next/current enum definition until an empty line and the block comment has been used.
+* **Block Comments:** Comments on a line of their own and not indented are added to the description of the next enum definition or the next enum literal definitions until an empty line and the block comment has been used.
 
 .. literalinclude:: ../../tests/data/data_model/example_msgs/package1/msg/SampleEnum.msg
   :language: python
@@ -75,8 +74,29 @@ Enum and Class Definition
 * **Indented Comment Lines:** Comments on a line of their own but indented are added to the description of the last encountered property or enum literal.
 * **Block Comments:** Comments on a line of their own and not indented are added to the descriptions of the next properties or added to the descriptions of the next/current enum until an empty line and the block comment has been used.
 
-.. literalinclude:: ../../tests/data/data_model/example_msgs/package2/msg/SampleClassEnum.msg
-  :language: python
+.. code-block:: python
+
+  # SampleClassEnum.msg
+  # Properties in SampleClassEnum can reference
+  # enums in the same file.
+
+  # This block comment is added to the
+  # enum description of SampleClassEnumType.
+  byte OK     = 0
+  byte WARN   = 1
+  byte ERROR  = 2
+  byte STALE  = 3
+
+  # This block comment is added to the
+  # enum description of Color.
+  byte COLOR_RED    = 0
+  byte COLOR_BLUE   = 1
+  byte COLOR_YELLOW = 2
+
+  uint8 field1    # This inline comment is added to
+                  # the description of field1.
+  uint8 field2
+
 
 Referencing enums
 =================

tests/data/data_model/example_msgs/package1/msg/types/SampleEnum.msg

@@ -18,4 +18,5 @@ uint8 SAMPLE_ENUM_VALUE_GREEN  = 3
 uint8 OK     = 0
 uint8 WARN   = 1
 uint8 ERROR  = 2
+
 uint8 STALE  = 3