Merge pull request #213 from OpenSimulationInterface/update/Documentation-v3.0.1-Update2

Update Documentation (resolves #210)

Author: jdsika

osi_common.proto

@@ -142,7 +142,7 @@ message Dimension3d
 // versions  (V2.xx) had an other definition.
 //
 // \par References:
-// \li [1] DIN ISO 8855:2013-11
+// - [1] DIN ISO 8855:2013-11
 //
 message Orientation3d
 {

osi_detectedobject.proto

@@ -259,7 +259,7 @@ message DetectedMovingObject
         // \c MovingObject::TYPE_PEDESTRIAN
         //
         // \par References:
-        // \li [1] https://en.wikipedia.org/wiki/Anatomical_terms_of_location
+        // - [1] https://en.wikipedia.org/wiki/Anatomical_terms_of_location
         //
         optional Orientation3d head_pose = 4;
 
@@ -276,7 +276,7 @@ message DetectedMovingObject
         // \c MovingObject::TYPE_PEDESTRIAN
         //
         // \par References:
-        // \li [2] https://en.wikipedia.org/wiki/Anatomical_terms_of_location
+        // - [2] https://en.wikipedia.org/wiki/Anatomical_terms_of_location
         //
         optional Orientation3d upper_body_pose = 5;
     }

osi_environment.proto

@@ -53,7 +53,7 @@ message EnvironmentalConditions
     // (I = Intensity of precipitation in mm per hour [mm/h])
     //
     // \par References:
-    // \li [1] PAULAT, Marcus, et al. A gridded dataset of hourly precipitation
+    // - [1] PAULAT, Marcus, et al. A gridded dataset of hourly precipitation
     // in Germany: Its construction, climatology and application.
     // Meteorologische Zeitschrift, 2008, 17. Jg. Nr. 6, S. 719-732.
     //
@@ -109,9 +109,9 @@ message EnvironmentalConditions
     // contrast of a distant object against its background.
     //
     // \par References:
-    // \li [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway. Transportation Research Board, 1996.
-    // \li [3] [StVO 17 chapter 3](https://www.stvo.de/strassenverkehrsordnung/101-17-beleuchtung)
-    // \li [4] [Homepage of the Meteorological Office](http://www.metoffice.gov.uk/guide/weather/observations-guide/how-we-measure-visibility)
+    // - [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway. Transportation Research Board, 1996.
+    // - [3] [StVO 17 chapter 3](https://www.stvo.de/strassenverkehrsordnung/101-17-beleuchtung)
+    // - [4] [Homepage of the Meteorological Office](http://www.metoffice.gov.uk/guide/weather/observations-guide/how-we-measure-visibility)
     //
     enum Fog
     {
@@ -175,11 +175,11 @@ message EnvironmentalConditions
     // [6] and standards for required lighting levels on roads [6, 7, 8, 9].
     //
     // \par References:
-    // \li [5] [The NIST Reference on Constants, Units, and Uncertainty](https://physics.nist.gov/cuu/Units/units.html)
-    // \li [6] [National Optical Astronomy Observatory](https://www.noao.edu/education/QLTkit/ACTIVITY_Documents/Safety/LightLevels_outdoor+indoor.pdf)
-    // \li [7] [Standards for required street lighting in the USA](http://www.wsdot.wa.gov/research/reports/fullreports/847.1.pdf)
-    // \li [8] [Canadian IES-RP-8 standards for road lighting - municipality of Saint-Gedeon-de-. Beauce](http://sslnet.ca/wp-content/uploads/2011/10/LTE-RT-2011-0076-Anglais.pdf)
-    // \li [9] [European standards for road lighting](http://courtneystrong.com/wp-content/uploads/2017/07/css-sl1-class-and-quality-of-street-lighting.pdf)
+    // - [5] [The NIST Reference on Constants, Units, and Uncertainty](https://physics.nist.gov/cuu/Units/units.html)
+    // - [6] [National Optical Astronomy Observatory](https://www.noao.edu/education/QLTkit/ACTIVITY_Documents/Safety/LightLevels_outdoor+indoor.pdf)
+    // - [7] [Standards for required street lighting in the USA](http://www.wsdot.wa.gov/research/reports/fullreports/847.1.pdf)
+    // - [8] [Canadian IES-RP-8 standards for road lighting - municipality of Saint-Gedeon-de-. Beauce](http://sslnet.ca/wp-content/uploads/2011/10/LTE-RT-2011-0076-Anglais.pdf)
+    // - [9] [European standards for road lighting](http://courtneystrong.com/wp-content/uploads/2017/07/css-sl1-class-and-quality-of-street-lighting.pdf)
     //
     enum AmbientIllumination
     {

osi_featuredata.proto

@@ -79,7 +79,7 @@ message SensorDetectionHeader
     // the sensor detection frame which uses e.g. spherical coordinates.
     //
     // \par References:
-    // \li [1] DIN ISO 8855:2013-11
+    // - [1] DIN ISO 8855:2013-11
     //
     optional MountingPosition mounting_position = 3;
 
@@ -211,7 +211,7 @@ message RadarDetection
 
     // The signal to noise ratio (SNR) of the radar detection.
     //
-    // Unit: [dB m^2]
+    // Unit: [dB]
     //
     optional double snr = 8;
 

osi_groundtruth.proto

@@ -125,8 +125,8 @@ message GroundTruth
     // Unit: []
     //
     // \par References:
-    // \li [1] [International Standard ISO 3166-1: Codes for the representation of names of countries and their subdivisions - Part 1: Country codes, third ed., 2013] (https://www.iso.org/obp/ui/)
-    // \li [2] [Wikipedia ISO 3166/1] (https://en.wikipedia.org/wiki/ISO_3166-1)
+    // - [1] [International Standard ISO 3166-1: Codes for the representation of names of countries and their subdivisions - Part 1: Country codes, third ed., 2013] (https://www.iso.org/obp/ui/)
+    // - [2] [Wikipedia ISO 3166/1] (https://en.wikipedia.org/wiki/ISO_3166-1)
     //
     optional uint32 country_code = 13;
 }

osi_lane.proto

@@ -257,7 +257,7 @@ message Lane
             // Unit: [mm/m]
             //
             // \par References:
-            // \li [1] SAYERS, M.W.; KARAMIHAS, S.M. Little Book of Profiling,
+            // - [1] SAYERS, M.W.; KARAMIHAS, S.M. Little Book of Profiling,
             // University of Michigan Transportation Research Institute, 1998.
             //
             optional double surface_roughness = 5;
@@ -272,9 +272,9 @@ message Lane
             // Unit: [m]
             //
             // \par References:
-            // \li [1] SAYERS, M.W.; KARAMIHAS, S.M. Little Book of Profiling,
+            // - [1] SAYERS, M.W.; KARAMIHAS, S.M. Little Book of Profiling,
             // University of Michigan Transportation Research Institute, 1998.
-            // \li [2] SCHNEIDER, R.: Modellierung der Wellenausbreitung fuer
+            // - [2] SCHNEIDER, R.: Modellierung der Wellenausbreitung fuer
             // ein bildgebendes Kfz-Radar, Dissertation, Universitaet Karlsruhe,
             // Mai 1998.
             //
@@ -315,10 +315,16 @@ message LaneBoundary
     // Since a \c BoundaryPoint is part of a sequence, only the position
     // attribute has to be set for each instance. All other values will be
     // reused from the previous \c BoundaryPoint in the sequence or set to
-    // default values if there is none or it was never set. For dashed lines,
-    // one \c BoundaryPoint has to be at the start and another at the end
-    // of each dashed line segment. For Botts' dots lines, one
-    // \c BoundaryPoint position has to define each Botts' dot.
+    // default values if there is none or it was never set. 
+    //
+    // \note For dashed lines, one \c BoundaryPoint has to be at the start and
+    // another at the end of each dashed line segment. The first 
+    // \c BoundaryPoint defines the beginning of the first dashed lane marking.
+    // The last \c BoundaryPoint defines the end of the last dashed lane 
+    // marking. For example, the area between the second and third 
+    // \c BoundaryPoint has no lane marking, and so on.
+    // \note For Botts' dots lines, one \c BoundaryPoint position has to define
+    // each Botts' dot.
     //
     // \attention For \c BoundaryPoint the same rule for the approximation
     // error applies as for \c Lane::Classification::centerline.

osi_object.proto

@@ -340,7 +340,7 @@ message MovingObject
     // Therefore the positive y-axis points to the left of the vehicle.
     //
     // \par References:
-    // \li [1] DIN ISO 8855:2013-11
+    // - [1] DIN ISO 8855:2013-11
     //
     message VehicleAttributes
     {

osi_sensordata.proto

@@ -168,7 +168,7 @@ message SensorData
     // \arg \b y-direction of sensor coordinate system: perpendicular to x and z right hand system
     //
     // \par References:
-    // \li [1] DIN ISO 8855:2013-11
+    // - [1] DIN ISO 8855:2013-11
     //
     // \note This field is usually static during the simulation.
     // \note The origin of vehicle's coordinate system in world frame is

osi_sensorview.proto

@@ -21,8 +21,8 @@ package osi3;
 // \c SensorView::mounting_position, except for the individual physical
 // technology-specific data, which is given with respect to the physical
 // sensor coordinate system specified in the corresponding physical sensor's
-// mounting_position, and the global_ground_truth, which is given in global
-// coordinates.
+// \c #mounting_position, and the \c #global_ground_truth, which is given in
+// global coordinates.
 //
 // When simulating multiple distinct sensors, each sensor can consume an
 // individual copy of the \c SensorView interface. This allows an independent
@@ -50,7 +50,7 @@ message SensorView
     //
     optional Timestamp timestamp = 2;
 
-    // The ID of the sensor at host vehicle's mounting_position.
+    // The ID of the sensor at host vehicle's \c #mounting_position.
     //
     // This is the ID of the virtual sensor, to be used in its detected
     // object output; it is distinct from the IDs of its physical detectors,
@@ -73,7 +73,7 @@ message SensorView
     // \arg \b y-direction of sensor coordinate system: perpendicular to x and z right hand system
     //
     // \par References:
-    // \li [1] DIN ISO 8855:2013-11
+    // - [1] DIN ISO 8855:2013-11
     //
     // \note This field is usually static during the simulation.
     // \note The origin of vehicle's coordinate system in world frame is
@@ -102,15 +102,15 @@ message SensorView
     //
     // This is the ground truth that is provided to the sensor model by the
     // simulation environment. It is filtered as per the requirements of the
-    // sensor model as expressed by the SensorViewConfiguration message(s)
+    // sensor model as expressed by the \c SensorViewConfiguration message(s)
     // that where exchanged during the simulation initialization phase.
     //
     // \note The host vehicle is always contained in the ground truth provided,
     // regardless of any filtering.
     //
     optional GroundTruth global_ground_truth = 7;
 
-    // The ID of the host vehicle in the ground_truth data.
+    // The ID of the host vehicle in the \c #global_ground_truth data.
     //
     optional Identifier host_vehicle_id = 8;
 
@@ -184,7 +184,7 @@ message RadarSensorView
     {
         // Relative signal level of the reflection.
         //
-        // This takes the combined_antenna_diagram (losses in TX and RX)
+        // This takes the combined antenna diagram (losses in TX and RX)
         // as well as the signal losses due to scattering and absorption
         // into account, and will, when multiplied by TX power yield the
         // actual RX power.
@@ -257,7 +257,7 @@ message LidarSensorView
     {
         // Relative signal level of the reflection.
         //
-        // This takes the combined_antenna_diagram (losses in TX and RX)
+        // This takes the combined antenna diagram (losses in TX and RX)
         // as well as the signal losses due to scattering and absorption
         // into account, and will, when multiplied by TX power yield the
         // actual RX power.