4.3.10 Commenting on fields and enums

The ASAM OSI® reference documentation is created using Doxygen. The reference documentation’s content is generated from comments in the .proto files. Follow these steps when creating comments on fields and enums to keep the documentation style consistent.

Prerequisites

  • You have created a field or enum.

Steps

  1. Add a description to the field or enum followed by an empty comment line.

  2. Add the unit of the field using the format Unit: UNIT followed by an empty comment line.

  3. Optionally, add notes using the keyword \note.

  4. Optionally, add literary references to the comments. The list of references starts with \par References: followed by the references. Every reference starts on a new line. Every reference begins with a reference number in the format [n]. Every reference ends with \n, except the last reference.

  5. Optionally, add rules encapsulated between \rules and \endrules.

Example

// \brief The conditions of the environment.
//
// \image html EnvironmentalConditions.svg
//
// Definition of light, weather conditions and other environmental conditions.
//
// \note These conditions apply locally around the host vehicle.
//
message EnvironmentalConditions
{
    // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2].
    //
    // Unit: Pa
    //
    // \note 100000 Pa = 1 bar
    //
    // \par References:
    // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
    // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
    //
    // \rules
    // is_optional
    // is_greater_than_or_equal_to: 90000
    // is_less_than_or_equal_to: 200000
    // \endrules
    //
    optional double atmospheric_pressure = 1;
}

Related topics