fix(docs): Doc review

Signed-off-by: Maximilian Rosin <[email protected]>

Author: max-rosin

osi_common.proto

@@ -215,52 +215,56 @@ message Identifier
     optional uint64 value = 1;
 }
 
-// \brief References to external objects
+// \brief References to external objects.
 //
 // The external reference is an optional recommendation to refer to objects defined outside of OSI.
 // This could be other OpenX standards, 3rd-party standards or user-defined objects.
 // simulation environments.
 //
-// \note The ExternalReference is an optional value and can be left empty.
+// \note ExternalReference is optional and can be left empty.
 //
 message ExternalReference
 {
-    // The source of the external references
+    // The source of the external references.
     //
     // Defines the original source of an object as uniquely identifiable reference.
     // In case of using \c GroundTruth::map_reference or 
     // \c GroundTruth::model_reference, the reference can be left empty.
-    // If not otherwise required, an URI is suggested and should follow the syntax according to 
+    // If not otherwise required, an URI is suggested. The syntax should follow 
     // \link https://tools.ietf.org/html/rfc3986 RFC 3986\endlink.
     //
     //
     optional string reference = 1;
 
-    // The type of the external references
+    // The type of the external references.
     //
-    // Must be used to describe the type of the original source.
+    // Mandatory value describing the type of the original source.
     //
     // For OpenX/ASAM standards it is specified as follows:
     // - net.asam.opendrive
     // - net.asam.openscenario
     //
-    // For third-party standards and user-defined objects the 
-    // Reverse Domain Name Notation, with lower case type field,
-    // is suggested, to guarantee unique and interoperable identifications.
+    // For third-party standards and user-defined objects, 
+    // reverse domain name notation with lower-case type field
+    // is recommended to guarantee unique and interoperable identification.
     //
     optional string type = 2;    
 
     // The external identifier reference value.
     //
-    // For a common description of the external identifier, where a wide range
-    // of identification types could be represented, the repeated string is chosen.
+    // The repeated string is chosen as a common description of the external
+    // identifier, because a variety of identificatier types could be
+    // involved .
     //
-    // E.g. referencing a unique lane in OpenDRIVE 
-    // (RoadId --> String, S-Value of LaneSection --> Double, LaneId --> Int)
+    // For example, referencing a unique lane in OpenDRIVE requires the
+    // following identifiers:
+    // * RoadId: String
+    // * S-Value of LaneSection: Double
+    // * LaneId: Int
     // 
     // \note The detailed description of the identifiers and how they are 
-    //       used for referencing external objects are given in the individual
-    //       messages, where it is deployed.
+    //       used for referencing external objects is given in the individual
+    //       messages where the external identifier is used.
     //
     // \see EnvironmentalConditions::source_reference
     // \see Lane::source_reference

osi_environment.proto

@@ -88,16 +88,16 @@ message EnvironmentalConditions
     //
     optional Fog fog = 7;
 
-    // Optional external Reference to the Environmental Condition Sources
+    // Optional external reference to the environmental condition sources.
     //
     // \note For OpenDRIVE and OpenSECNARIO there is no direct counterpart.
     //
-    // \note For non-ASAM Standards, it is implementation-specific how
+    // \note For non-ASAM standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       object is derived from only one origin source, like from one 
-    //       scernario file and from the sensors.
+    // \note The value has to be repeated because one object may be derived
+    //       from more than one origin source, for example, from a scenario file
+    //       and from sensors.
     //
     repeated ExternalReference source_reference = 9;
 

osi_lane.proto

@@ -50,13 +50,13 @@ message Lane
     //
     optional Classification classification = 2;
 
-    // Optional external Reference to the Lane Source
+    // Optional external reference to the lane source.
     //
-    // The ExternalReference point to the source of the lane, if it is derived
-    // from one or more objects or external references. An example here is the 
-    // reference to the lane defined in a OpenDRIVE map.
+    // The external reference points to the source of the lane, if it is derived
+    // from one or more objects or external references.
     //
-    // For OpenDRIVE the items should be set as following:
+    // For example, to reference a lane defined in an OpenDRIVE map
+    // the items should be set as following:
     // * reference = URI to map, can remain empty if identical with definiton
     //               in \c GroundTruth::map_reference
     // * type = "net.asam.opendrive"
@@ -68,10 +68,9 @@ message Lane
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       Lane-Segment is derived from only one origin segment. It is also
-    //       possible, that multiple sources (map, sensor) should be added as
-    //       reference.
+    // \note The value has to be repeated, because one lane segment may be
+    //       derived from more than one origin segment. Multiple sources
+    //       may be added as reference as well, for example, a map and sensors.
     //
     repeated ExternalReference source_reference = 3;
 
@@ -750,17 +749,17 @@ message LaneBoundary
     //
     optional Classification classification = 3;
 
-    // Optional external Reference to the Lane Boundary Source
+    // Optional external reference to the lane boundary source.
     //
-    // \note For OpenDRIVE there is no direct possibility to reference the
+    // \note For OpenDRIVE, there is no direct possibility to reference the
     //       RoadMark, as there is no unique identifier in this sub-object.
     //
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       object is derived from only one origin source, like from one 
-    //       scernario file and and from the sensors.
+    // \note The value has to be repeated because one object may be derived
+    //       from more than one origin source, for example, from a scenario file
+    //       and from sensors.
     //
     repeated ExternalReference source_reference = 4;
 

osi_object.proto

@@ -40,36 +40,36 @@ message StationaryObject
     //
     optional string model_reference = 4;
 
-    // External Reference to the StationaryObject Source
+    // External reference to the stationary-object source.
     //
-    // The ExternalReference point to the source of an stationary object, if it
+    // The external reference points to the source of a stationary object, if it
     // is derived from an external sources like OpenDRIVE or OpenSCENARIO.
     //
-    // For OpenDRIVE the objects should be set as following:
+    // For OpenDRIVE, references to objects should be set as following:
     // * reference = URI to map, can remain empty if identical with definiton
     //               in \c GroundTruth::map_reference
     // * type = "net.asam.opendrive"
     // * identifier[0] = "object" for t_road_objects_object and
     //                   "bridge" for t_road_objects_bridge
     // * identifier[1] = id of t_road_objects_object or t_road_objects_bridge
     //
-    // For OpenSCENARIO the entities of the type MiscObject, which describes
-    // partly stationary objects should be set as following:
+    // For OpenSCENARIO, references to entities of the type MiscObject, which
+    // describes partly stationary objects, should be set as following:
     // * reference = URI to the OpenSCENARIO File
     // * type = "net.asam.openscenario"
     // * identifier[0] = Entity-Type ("MiscObject")
     // * identifier[1] = name of MiscObject in Entity
     //
-    // \note The following rule, described in OpenDRIVE, should also apply here:
+    // \note The following rule, described in OpenDRIVE, also applies:
     // * Objects derived from OpenSCENARIO shall not be mixed with objects
     //   described in OpenDRIVE.
     //
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       object is derived from only one origin source, like from one 
-    //       scenario file and and from the sensors.
+    // \note The value has to be repeated because one object may be derived
+    //       from more than one origin source, for example, from a scenario file
+    //       and from sensors.
     //
     repeated ExternalReference source_reference = 5;
 
@@ -392,13 +392,13 @@ message MovingObject
     //
     optional MovingObjectClassification moving_object_classification = 9;    
 
-    // Optional external Reference to the MovingObject Source
+    // Optional external reference to the moving-object source
     //
-    // The ExternalReference point to the source of an moving object, if it
+    // The external reference points to the source of an moving object, if it
     // is derived from an external sources like OpenSCENARIO.
     //
-    // For OpenSCENARIO the entities of the type Vehicle or Pedestrian,
-    // which describes moving objecs should be set as following:
+    // For OpenSCENARIO, references to entities of the type Vehicle or
+    // Pedestrian, which describe moving objects, should be set as following:
     // * reference = URI to the OpenSCENARIO File
     // * type = "net.asam.openscenario"
     // * identifier[0] = Entity-Type ("Vehicle" or "Pedestrian")
@@ -409,9 +409,9 @@ message MovingObject
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       object is derived from only one origin source, like from one map
-    //       and from the sensors.
+    // \note The value has to be repeated because one object may be derived
+    //       from more than one origin source, for example, from a scenario file
+    //       and from sensors.
     //
     repeated ExternalReference source_reference = 10;
 

osi_occupant.proto

@@ -23,16 +23,16 @@ message Occupant
     //
     optional Classification classification = 2;
 
-    // External Reference to the Occupant Source
+    // External reference to the occupant source.
     //
-    // \note For OpenDRIVE and OpenSCENARIO there is no no direct counterpart.
+    // \note For OpenDRIVE and OpenSCENARIO there is no direct counterpart.
     //
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       object is derived from only one origin source, like from one 
-    //       scernario file and and from the sensors.
+    // \note The value has to be repeated because one object may be derived
+    //       from more than one origin source, for example, from a scenario file
+    //       and from sensors.
     //
     repeated ExternalReference source_reference = 3;
 

osi_roadmarking.proto

@@ -55,9 +55,9 @@ message RoadMarking
     //
     optional Classification classification = 3;
 
-    // Optional external Reference to the Roadmarking Source
+    // Optional external reference to the road-marking source.
     //
-    // The ExternalReference point to the source of the surface marking, if it
+    // The external reference points to the source of the surface marking, if it
     // is derived from one or more objects or external references. An example
     // here is the reference to the signal defined in a OpenDRIVE map.
     //
@@ -67,20 +67,17 @@ message RoadMarking
     // * type = "net.asam.opendrive"
     // * identifier[0] = id of t_road_signals_signal
     //
-    // \note In OpenDRIVE there is also the possibility to define surface
-    //       markings as an object. In this case, the associated object is
-    //       usually referenced within OpenDRIVE using the reference
-    //       t_road_signals_signal_reference, which allows it to be
-    //       identifiable.
+    // \note With OpenDRIVE, surface markings can also be defined as objects.
+    //       In this case, the associated object is usually referenced within
+    //       OpenDRIVE using the reference t_road_signals_signal_reference.
     //       An additional reference to the object is therefore not necessary.
     //
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       Lane-Segment is derived from only one origin segment. It is also
-    //       possible, that multiple sources (map, sensor) should be added as
-    //       reference.
+    // \note The value has to be repeated, because one lane segment may be
+    //       derived from more than one origin segment. Multiple sources
+    //       may be added as reference as well, for example, a map and sensors.
     //
     repeated ExternalReference source_reference = 4;
 

osi_trafficlight.proto

@@ -42,25 +42,24 @@ message TrafficLight
     //
     optional string model_reference = 4;
 
-    // Optional external Reference to the Traffic Light Source
+    // Optional external reference to the traffic light source.
     //
-    // The ExternalReference point to the source of the traffic light, if it is
-    // derived from one or more objects or external references. An example here
-    // is the reference to the signal defined in a OpenDRIVE map.
+    // The external reference points to the source of the traffic light, if it 
+    // is derived from one or more objects or external references.
     //
-    // For OpenDRIVE the items should be set as following:
-    // * reference = URI to map, can remain empty if identical with definiton
+    // For example, to reference a signal defined in an OpenDRIVE map
+    // the items should be set as following:
+    // * reference = URI to map, can remain empty if identical with definition
     //               in \c GroundTruth::map_reference
     // * type = "net.asam.opendrive"
     // * identifier[0] = id of t_road_signals_signal
     //
     // \note For non-ASAM Standards, it is implementation-specific how
     //       source_reference is resolved.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       Lane-Segment is derived from only one origin segment. It is also
-    //       possible, that multiple sources (map, sensor) should be added as
-    //       reference.
+    // \note The value has to be repeated, because one lane segment may be
+    //       derived from more than one origin segment. Multiple sources
+    //       may be added as reference as well, for example, a map and sensors.
     //
     repeated ExternalReference source_reference = 5;
 

osi_trafficsign.proto

@@ -157,13 +157,13 @@ message TrafficSign
     repeated SupplementarySign supplementary_sign = 3;
 
 
-    // Optional external Reference to the Traffic Sign Source
+    // Optional external reference to the traffic sign source.
     //
-    // The ExternalReference point to the source of the traffic sign, if it is
-    // derived from one or more objects or external references. An example here
-    // is the reference to the signal defined in a OpenDRIVE map.
+    // The external reference point to the source of the traffic sign, if it is
+    // derived from one or more objects or external references.
     //
-    // For OpenDRIVE the items should be set as following:
+    // For example, to reference a signal defined in an OpenDRIVE map
+    // the items should be set as following:
     // * reference = URI to map, can remain empty if identical with definition
     //               in \c GroundTruth::map_reference
     // * type = "net.asam.opendrive"
@@ -173,13 +173,12 @@ message TrafficSign
     //       source_reference is resolved.
     //
     // \note If an individual identification of MainSign and SupplementarySign
-    //       is be necessary, this sould be defined via multiple individual
+    //       is necessary, this should be done via multiple individual
     //       entries of this source_reference.
     //
-    // \note The value has to be repeated, as it cannot guarantee, that one
-    //       Lane-Segment is derived from only one origin segment. It is also
-    //       possible, that multiple sources (map, sensor) should be added as
-    //       reference.
+    // \note The value has to be repeated, because one lane segment may be
+    //       derived from more than one origin segment. Multiple sources
+    //       may be added as reference as well, for example, a map and sensors.
     //
     repeated ExternalReference source_reference = 4;