Documentation/v3.0.1 update 7

.travis.yml

@@ -81,6 +81,7 @@ script:
     - cmake -D FILTER_PROTO2CPP_PY_PATH=${DEPS_DIR}/proto2cpp ..
     - doxygen
     - cd ..
+    - python test_cases_doc.py
 
 # Deploy the documentation on github (only for master branch).
 deploy:

README.md

@@ -102,9 +102,7 @@ Copy the content of the repo proto2cpp to your desired `<path-to-proto2cpp.py>`
 Citing
 ------
 
-Use the following citation for referencing the OSI interface in your scientific work:
-
-`@misc{osi.2017,
+Use the following citation for referencing the OSI interface in your scientific work: `@misc{osi.2017,
         author = {Hanke, Timo and Hirsenkorn, Nils and {van~Driesten}, Carlo and {Garcia~Ramos}, Pilar and Schiementz, Mark and Schneider, Sebastian},
         year = {2017},
         title = {{Open Simulation Interface: A generic interface for the environment perception of automated driving functions in virtual scenarios.}},

doxygen_config.cmake.in

@@ -21,6 +21,7 @@ INPUT_FILTER           = "python @FILTER_PROTO2CPP_PY_PATH@/proto2cpp.py"
 HAVE_DOT               = YES
 HIDE_UNDOC_RELATIONS   = NO
 MAX_DOT_GRAPH_DEPTH    = 2
+SORT_MEMBER_DOCS       = YES
 
 # If someone wants UML diagrams in the documentation, the next parameter must 
 # be commented in.

open_simulation_interface-config-version.cmake.in

@@ -18,4 +18,4 @@ else()
   else()
     set(PACKAGE_VERSION_COMPATIBLE FALSE)
   endif()
-endif()
+endif()

osi_common.proto

@@ -136,7 +136,6 @@ message Dimension3d
 // <tt>Rotation_yaw_pitch_roll = Rotation_roll*Rotation_pitch*Rotation_yaw</tt>
 //
 // <tt>vector_global_coord_system := Inverse_Rotation_yaw_pitch_roll(</tt><tt>Orientation3d</tt><tt>)*(vector_local_coord_system) + local_origin::position</tt>
-
 //
 // \attention This definition changed in OSI version 3.0.0. Previous OSI
 // versions  (V2.xx) had an other definition.

osi_detectedlane.proto

@@ -118,4 +118,4 @@ message DetectedLaneBoundary
         //
         optional LaneBoundary.Classification classification = 2;
     }
-}
+}

osi_featuredata.proto

@@ -112,7 +112,7 @@ message SensorDetectionHeader
     optional Identifier sensor_id = 7;
 
     //
-    // \brief Data qualifier communicates the overall availability of the
+    // Data qualifier communicates the overall availability of the
     // interface.
     //
     enum DataQualifier

osi_roadmarking.proto

@@ -109,9 +109,9 @@ message RoadMarking
             //
             TYPE_PAINTED_TRAFFIC_SIGN = 2;
 
-            // Paint on the road surface indicating a monochrome logical symbol of a
-            // traffic sign (e.g. digits 50 as start of speed limit 50 or stop line
-            // for stop sign).
+            // Paint on the road surface indicating a monochrome logical symbol
+            // of a traffic sign (e.g. digits 50 as start of speed limit 50 or
+            // stop line for stop sign).
             //
             TYPE_SYMBOLIC_TRAFFIC_SIGN = 3;
 

osi_sensordata.proto

@@ -39,7 +39,7 @@ message DetectedEntityHeader
     optional DataQualifier data_qualifier = 3;
 
     //
-    // \brief Data qualifier communicates the overall availability of the
+    // Data qualifier communicates the overall availability of the
     // interface.
     //
     enum DataQualifier

osi_version.proto.in

@@ -11,7 +11,7 @@ package osi3;
 //
 // The field denoting the version number. This needs to be set by the
 // sender to the actual OSI version that is to be sent.  Code wanting to
-// access the version number of the OSI code base can access a FileOption,
+// access the version number of the OSI code base can access a FileOptions,
 // which has the proper values, like this:
 //
 // @code
@@ -44,8 +44,12 @@ message InterfaceVersion
     optional uint32 version_patch = 3;
 }
 
-
+//
+// \brief Extension of \c FileOptions for OSI
+//
 extend google.protobuf.FileOptions {
+    // Extend \c FileOptions with current interface version of OSI
+    //
     optional InterfaceVersion current_interface_version = 81000;
 }
 

test_cases.py

@@ -12,9 +12,12 @@
         enumName = ""
         noMessage = 0
         noComment = 0
+        hasBrief = False
+        hasNewLine = True
 
         for line in fin:
             i = i + 1
+            hasNewLine = line.endswith("\n")
 
             # --------------------------------------------------------------
             # Test case 1 is checking if there are illegal tabulators in the code
@@ -59,8 +62,14 @@
                 matchComment = re.search("//", line)
                 if matchComment is not None:
                     statement = line[:matchComment.start()]
+                    comment = line[matchComment.end():]
                 else:
                     statement = line
+                    comment = ""
+
+                # New line is not necessary. Remove for a better output.
+                statement = statement.replace("\n", "")
+                comment = comment.replace("\n", "")
 
                 # --------------------------------------------------------------
                 # Test case 6-8 camelcase for enums and check enum name?
@@ -110,7 +119,7 @@ def convert(name):
                     state = 1
 
                 # --------------------------------------------------------------
-                # Test case 10-12 check message name, field type and field name
+                # Test case 10-12,18 check message name, field type and field name
                 #
                 # Check (nested) messages
 
@@ -131,6 +140,9 @@ def convert(name):
                             if matchNameConv is None:
                                 print(file + " in line " + str(i) + ": message name wrong. '"+endOfLine[matchName.start():matchName.end()]+"'")
                                 state = 1
+                    elif re.search(r"\bextend\b", statement) is not None:
+                        # treat extend as message
+                        noMessage += 1
                     else:
                         # Check field names
                         if noMessage > 0:
@@ -151,24 +163,61 @@ def convert(name):
                                     if matchNameConv is None:
                                         print(file + " in line " + str(i) + ": field message type wrong. Check: '"+checkType+"'")
                                         state = 1
+
+                                if re.search(r"\boptional\b",type) is None and re.search(r"\brepeated\b",type) is None:
+                                    # Test 18 has every field the multiplicity "repeated" or "optional"
+                                    print(file + " in line " + str(i) + ": field multiplicity (\"optional\" or \"repeated\") is missing. Check: '"+statement+"'")
+                                    state = 1
 
                     # Search for a closing brace.
                     matchClosingBrace = re.search("}", statement)
                     if noMessage > 0 and matchClosingBrace is not None:
                         noMessage -= 1
 
                 # --------------------------------------------------------------
-                # Test case 13 is checking if comment is min. 2 lines
+                # Test case 13-17 is checking comment
                 if line.find("//") != -1:
                     noComment += 1;
+                    if comment.find("\\brief") != -1:
+                        hasBrief = True;
                 else:
+                    # Test case 13 is checking if comment is min. 2 lines
                     if noComment == 1:
                         print(file + " in line " + str(i-1) + ": short comment - min. 2 lines.")
                         state = 1
-                    noComment = 0
+                    if re.search(r"\bmessage\b", statement) is not None or re.search(r"\bextend\b", statement) is not None:
+                        if hasBrief == False:
+                            # Test case 14 each message and extend has a \brief comment
+                            print(file + " in line " + str(i-1) + ": \\brief section in comment is missing for: '"+statement+"'")
+                            state = 1
+                    elif hasBrief == True:
+                        # Test case 15 only message and extend has a \brief comment
+                        print(file + " in line " + str(i-1) + ": \\brief section in comment is not necessary for: '"+statement+"'")
+                        state = 1
+
+                    if re.search(r"\bmessage\b", statement) is not None or re.search(r"\bextend\b", statement) is not None or re.search(r"\benum\b", statement) is not None:
+                        if noComment == 0:
+                            # Test case 16 every message, extend or enum has a comment
+                            print(file + " in line " + str(i) + ": comment is missing for: '"+statement+"'")
+                            state = 1
 
+                    if noMessage > 0 or isEnum == True:
+                        if statement.find(";") != -1:
+                            if noComment == 0:
+                                # Test case 17 every statement has a comment
+                                print(file + " in line " + str(i) + ": comment is missing for: '"+statement+"'")
+                                state = 1
+
+                    noComment = 0
+                    hasBrief = False
+
                 # --------------------------------------------------------------
-
+                # Next Test 20
+
+
+        # Test case 19 last line must end with a new line.
+        if hasNewLine == False:
+            print(file + " has no new line at the end of the file.")
+            state = 1
 
 sys.exit(state)
-

test_cases_doc.py

@@ -0,0 +1,24 @@
+import sys
+import unicodedata
+import re
+from glob import *
+
+state = 0
+
+for file in glob("doc/html/*.htm*"):
+    with open(file, "rt") as fin:
+        i = 0
+
+        for line in fin:
+            i = i + 1
+
+            # --------------------------------------------------------------
+            # Test case 1 is checking if there are illegal hash chars in the
+            # documentation. -> doxygen link not found.
+            matchHash = re.search(r"([\s>]|^)#\w(\S)*",line)
+            if matchHash is not None:
+                print(file + " in line " + str(i) + ": not permitted hash found. Search for: '"+line[matchHash.start():matchHash.end()])
+                state = 1
+
+
+sys.exit(state)