Improved rst parser; fixed bug in hdr_parser; some small fixes in documentation

modules/calib3d/doc/camera_calibration_and_3d_reconstruction.rst

@@ -1197,9 +1197,9 @@ The method executes the SGBM algorithm on a rectified stereo pair. See ``stereo_
 
 stereoCalibrate
 -------------------
-.. ocv:function:: double stereoCalibrate( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray cameraMatrix1, InputOutputArray distCoeffs1, InputOutputArray cameraMatrix2, InputOutputArray distCoeffs2, Size imageSize, OutputArray R, OutputArray T, OutputArray E, OutputArray F, TermCriteria term_crit = TermCriteria(TermCriteria::COUNT+                         TermCriteria::EPS, 30, 1e-6), int flags=CALIB_FIX_INTRINSIC )
+Calibrates the stereo camera.
 
-    Calibrates the stereo camera.
+.. ocv:function:: double stereoCalibrate( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray cameraMatrix1, InputOutputArray distCoeffs1, InputOutputArray cameraMatrix2, InputOutputArray distCoeffs2, Size imageSize, OutputArray R, OutputArray T, OutputArray E, OutputArray F, TermCriteria term_crit = TermCriteria(TermCriteria::COUNT+                         TermCriteria::EPS, 30, 1e-6), int flags=CALIB_FIX_INTRINSIC )
 
 .. ocv:pyfunction:: cv2.stereoCalibrate(objectPoints, imagePoints1, imagePoints2, cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, imageSize[, R[, T[, E[, F[, criteria[, flags]]]]]]) -> retval, cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, R, T, E, F
 
@@ -1287,11 +1287,10 @@ Similarly to :ocv:func:`calibrateCamera` , the function minimizes the total re-p
 
 stereoRectify
 -----------------
+Computes rectification transforms for each head of a calibrated stereo camera.
 
 .. ocv:function:: void stereoRectify( InputArray cameraMatrix1, InputArray distCoeffs1, InputArray cameraMatrix2, InputArray distCoeffs2, Size imageSize, InputArray R, InputArray T, OutputArray R1, OutputArray R2, OutputArray P1, OutputArray P2, OutputArray Q, int flags=CALIB_ZERO_DISPARITY, double alpha, Size newImageSize=Size(), Rect* roi1=0, Rect* roi2=0 )
 
-    Computes rectification transforms for each head of a calibrated stereo camera.
-
 .. ocv:cfunction:: void cvStereoRectify( const CvMat* cameraMatrix1, const CvMat* cameraMatrix2, const CvMat* distCoeffs1, const CvMat* distCoeffs2, CvSize imageSize, const CvMat* R, const CvMat* T, CvMat* R1, CvMat* R2, CvMat* P1, CvMat* P2, CvMat* Q=0, int flags=CV_CALIB_ZERO_DISPARITY, double alpha=-1, CvSize newImageSize=cvSize(0, 0), CvRect* roi1=0, CvRect* roi2=0)
 .. ocv:pyoldfunction:: cv.StereoRectify( cameraMatrix1, cameraMatrix2, distCoeffs1, distCoeffs2, imageSize, R, T, R1, R2, P1, P2, Q=None, flags=CV_CALIB_ZERO_DISPARITY, alpha=-1, newImageSize=(0, 0))-> (roi1, roi2)
 
@@ -1374,13 +1373,14 @@ See below the screenshot from the ``stereo_calib.cpp`` sample. Some red horizont
 
 stereoRectifyUncalibrated
 -----------------------------
-.. ocv:function:: bool stereoRectifyUncalibrated( InputArray points1, InputArray points2, InputArray F, Size imgSize, OutputArray H1, OutputArray H2, double threshold=5 )
+Computes a rectification transform for an uncalibrated stereo camera.
 
-    Computes a rectification transform for an uncalibrated stereo camera.
+.. ocv:function:: bool stereoRectifyUncalibrated( InputArray points1, InputArray points2, InputArray F, Size imgSize, OutputArray H1, OutputArray H2, double threshold=5 )
 
 .. ocv:pyfunction:: cv2.stereoRectifyUncalibrated(points1, points2, F, imgSize[, H1[, H2[, threshold]]]) -> retval, H1, H2
 
 .. ocv:cfunction:: void cvStereoRectifyUncalibrated( const CvMat* points1, const CvMat* points2, const CvMat* F, CvSize imageSize, CvMat* H1, CvMat* H2, double threshold=5 )
+
 .. ocv:pyoldfunction:: cv.StereoRectifyUncalibrated(points1, points2, F, imageSize, H1, H2, threshold=5)-> None
 
     :param points1: Array of feature points in the first image.

modules/java/rst_parser.py

@@ -160,6 +160,8 @@ class RstParser(object):
                 skip_code_lines = True
                 continue
 
+            # todo: parse ".. seealso::" sections
+
             # parse class & struct definitions
             if ll.startswith(".. ocv:class::"):
                 func["class"] = ll[ll.find("::")+2:].strip()
@@ -265,7 +267,7 @@ class RstParser(object):
 
         # don't forget about the last function section in file!!!
         if len(lines) > 1:
-            self.parse_section_safe(module_name, fname, doc, flineno, lines[:len(lines)])
+            self.parse_section_safe(module_name, fname, doc, flineno, lines)
 
     def parse_namespace(self, func, section_name):
         known_namespaces = ["cv", "gpu", "flann"]
@@ -327,7 +329,30 @@ class RstParser(object):
              print "RST parser error: \"%s\" from file: %s (line %s) is already documented in file: %s (line %s)" \
                  % (func["name"], func["file"], func["line"], self.definitions[func["name"]]["file"], self.definitions[func["name"]]["line"])
              return False
-        #todo: validate parameter names
+        return self.validateParams(func)
+
+    def validateParams(self, func):
+        documentedParams = func.get("params",{}).keys()
+        params = []
+       	
+        for decl in func.get("decls", []):
+            if len(decl) > 2:
+                args = decl[2][3] # decl[2] -> [ funcname, return_ctype, [modifiers], [args] ]
+                for arg in args:
+                    # arg -> [ ctype, name, def val, [mod], argno ]
+                    if arg[0] != "...":
+                        params.append(arg[1])
+        params = list(set(params))#unique
+
+        # 1. all params are documented
+        for p in params:
+            if p not in documentedParams:
+                print "RST parser warning: parameter \"%s\" of \"%s\" is undocumented. File: %s (line %s)" % (p, func["name"], func["file"], func["line"])
+
+        # 2. only real params are documented
+        for p in documentedParams:
+            if p not in params:
+                print "RST parser warning: unexisting parameter \"%s\" of \"%s\" is documented. File: %s (line %s)" % (p, func["name"], func["file"], func["line"])
         return True
 
     def normalize(self, func):
@@ -444,7 +469,7 @@ if __name__ == "__main__":
     parser = RstParser(hdr_parser.CppHeaderParser())
     
     if module == "all":
-        for m in ["androidcamera", "calib3d", "contrib", "core", "features2d", "flann", "gpu", "haartraining", "highgui", "imgproc", "java", "legacy", "ml", "objdetect", "ocl", "python", "stitching", "traincascade", "ts", "video"]:
+        for m in ["core", "flann", "imgproc", "ml", "highgui", "video", "features2d", "calib3d", "objdetect", "legacy", "contrib", "gpu", "androidcamera", "haartraining", "java", "ocl", "python", "stitching", "traincascade", "ts"]:
             parser.parse(m, os.path.join(rst_parser_dir, "../" + m))
     else:
         parser.parse(module, os.path.join(rst_parser_dir, "../" + module))

modules/python/src2/hdr_parser.py

@@ -294,10 +294,12 @@ class CppHeaderParser(object):
                 if dfpos >= 0:
                     defval = arg[dfpos+1:].strip()
                     arg = arg[:dfpos].strip()
-                pos = arg.rfind(" ")
+                pos = len(arg)-1
+                while pos >= 0 and (arg[pos] == "_" or arg[pos].isalpha() or arg[pos].isdigit()):
+                    pos -= 1
                 if pos >= 0:
                     aname = arg[pos+1:].strip()
-                    atype = arg[:pos].strip()
+                    atype = arg[:pos+1].strip()
                     if aname.endswith("&") or aname.endswith("*") or (aname in ["int", "string", "Mat"]):
                         atype = (atype + " " + aname).strip()
                         aname = "param"