Documentation/v3.0.1 update 7 (#224)

carsten-kuebler · jdsika · commit c19f9d6bf7a3 · 2018-04-27T09:57:31.000+02:00
* Additional test cases for comments

* Optimize output

Remove "\n" in error messages.

* Check for optional and repeated

Every field must have optional or repeated.

* Check end of files

if newline is at the end of each file

* Add unit test cases for doxygen documentation

Add \c
Add  doxygen test cases to travis.yml
Remove special char in roadmarking (problem for doxygen windows)
Add documentation for extended class in osi_version.proto.in

* Extend error message

* Bugfix readme.md and doxygen
diff --git a/.travis.yml b/.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:
diff --git a/README.md b/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.}},
diff --git a/doxygen_config.cmake.in b/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.
diff --git a/open_simulation_interface-config-version.cmake.in b/open_simulation_interface-config-version.cmake.in
@@ -18,4 +18,4 @@ else()
   else()
     set(PACKAGE_VERSION_COMPATIBLE FALSE)
   endif()
-endif()
+endif()
diff --git a/osi_common.proto b/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.
diff --git a/osi_detectedlane.proto b/osi_detectedlane.proto
@@ -118,4 +118,4 @@ message DetectedLaneBoundary
         //
         optional LaneBoundary.Classification classification = 2;
     }
-}
+}
diff --git a/osi_featuredata.proto b/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
diff --git a/osi_roadmarking.proto b/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;
 
diff --git a/osi_sensordata.proto b/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
diff --git a/osi_version.proto.in b/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;
 }
 
diff --git a/test_cases.py b/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)
-
diff --git a/test_cases_doc.py b/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)

-Original file line number
+Diff line change
   else()
     set(PACKAGE_VERSION_COMPATIBLE FALSE)
   endif()
 -endif()
 +endif()
Original file line number	Diff line number	Diff line change
`@@ -118,4 +118,4 @@ message DetectedLaneBoundary`
`118`	`118`	`//`
`119`	`119`	`optional LaneBoundary.Classification classification = 2;`
`120`	`120`	`}`
`121`		`-}`
	`121`	`+}`