Fixed several false-positive warnings in rst_parser.py. (Now it detects 553 undocumented parameters for #1205.)

modules/calib3d/doc/camera_calibration_and_3d_reconstruction.rst

@@ -115,7 +115,7 @@ Finds the camera intrinsic and extrinsic parameters from several views of a cali
 
 .. ocv:pyfunction:: cv2.calibrateCamera(objectPoints, imagePoints, imageSize[, cameraMatrix[, distCoeffs[, rvecs[, tvecs[, flags[, criteria]]]]]]) -> retval, cameraMatrix, distCoeffs, rvecs, tvecs
 
-.. ocv:cfunction:: double cvCalibrateCamera2( const CvMat* objectPoints, const CvMat* imagePoints, const CvMat* pointCounts, CvSize imageSize, CvMat* cameraMatrix, CvMat* distCoeffs, CvMat* rvecs=NULL, CvMat* tvecs=NULL, int flags=0, CvTermCriteria term_crit CV_DEFAULT(cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,DBL_EPSILON)) )
+.. ocv:cfunction:: double cvCalibrateCamera2(const CvMat* objectPoints, const CvMat* imagePoints, const CvMat* pointCounts, CvSize imageSize, CvMat* cameraMatrix, CvMat* distCoeffs, CvMat* rvecs=NULL, CvMat* tvecs=NULL, int flags=0, CvTermCriteria term_crit = cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,DBL_EPSILON) )
 
 .. ocv:pyoldfunction:: cv.CalibrateCamera2(objectPoints, imagePoints, pointCounts, imageSize, cameraMatrix, distCoeffs, rvecs, tvecs, flags=0)-> None
 
@@ -153,7 +153,9 @@ Finds the camera intrinsic and extrinsic parameters from several views of a cali
 
         * **CV_CALIB_RATIONAL_MODEL** Coefficients k4, k5, and k6 are enabled. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the rational model and return 8 coefficients. If the flag is not set, the function computes  and returns  only 5 distortion coefficients.
 
-    :param criteria: Termination criteria for the iterative optimization algorithm. 
+    :param criteria: Termination criteria for the iterative optimization algorithm.
+
+    :param term_crit: same as ``criteria``.
 
 The function estimates the intrinsic camera
 parameters and extrinsic parameters for each of the views. The algorithm is based on [Zhang2000] and [BoughuetMCT]. The coordinates of 3D object points and their corresponding 2D projections

modules/imgproc/doc/histograms.rst

@@ -405,8 +405,8 @@ Creates a histogram.
 The function creates a histogram of the specified size and returns a pointer to the created histogram. If the array ``ranges`` is 0, the histogram bin ranges must be specified later via the function  :ocv:cfunc:`SetHistBinRanges`. Though :ocv:cfunc:`CalcHist` and :ocv:cfunc:`CalcBackProject` may process 8-bit images without setting bin ranges, they assume they are equally spaced in 0 to 255 bins.
 
 
-GetHistValue*D
---------------
+GetHistValue_?D
+---------------
 Returns a pointer to the histogram bin.
 
 .. ocv:cfunction:: float cvGetHistValue_1D(CvHistogram hist, int idx0)

modules/java/rst_parser.py

@@ -4,6 +4,36 @@ verbose = False
 show_warnings = True
 show_errors = True
 
+params_blacklist = {
+    "fromarray" : ("object", "allowND"), # python only function
+    "reprojectImageTo3D" : ("ddepth"),   # python only argument
+    "composeRT" : ("d*d*"),              # wildchards in parameter names are not supported by this parser
+    "CvSVM::train_auto" : ("\*Grid"),    # wildchards in parameter names are not supported by this parser
+    "error" : "args", # parameter of supporting macro
+    "getConvertElem" : ("from", "cn", "to", "beta", "alpha"), # arguments of returned functions
+    "gpu::swapChannels" : ("dstOrder") # parameter is not parsed correctly by the hdr_parser
+}
+
+params_mapping = {
+    "composeRT" : {
+        "dr3dr1" : "d*d*",
+        "dr3dr2" : "d*d*",
+        "dr3dt1" : "d*d*",
+        "dr3dt2" : "d*d*",
+        "dt3dr1" : "d*d*",
+        "dt3dr2" : "d*d*",
+        "dt3dt1" : "d*d*",
+        "dt3dt2" : "d*d*"
+        },
+    "CvSVM::train_auto" : {
+        "coeffGrid" : "\\*Grid",
+        "degreeGrid" : "\\*Grid",
+        "gammaGrid" : "\\*Grid",
+        "nuGrid" : "\\*Grid",
+        "pGrid" : "\\*Grid"
+    }
+}
+
 class DeclarationParser(object):
     def __init__(self, line=None):
         if line is None:
@@ -325,8 +355,10 @@ class RstParser(object):
         params =  func.get("params",{})
         if decl.name in params:
             if show_errors:
-                print >> sys.stderr, "RST parser error: redefinition of parameter \"%s\" in \"%s\" File: %s (line %s)" \
-                    % (decl.name, func["name"], func["file"], func["line"])
+                #check black_list
+                if decl.name not in params_blacklist.get(func["name"], []):
+                    print >> sys.stderr, "RST parser error: redefinition of parameter \"%s\" in \"%s\" File: %s (line %s)" \
+                        % (decl.name, func["name"], func["file"], func["line"])
         else:
             params[decl.name] = decl.comment
             func["params"] = params
@@ -389,13 +421,19 @@ class RstParser(object):
         # 2. only real params are documented
         for p in documentedParams:
             if p not in params and show_warnings:
-                print >> sys.stderr, "RST parser warning: unexisting parameter \"%s\" of \"%s\" is documented. File: %s (line %s)" % (p, func["name"], func["file"], func["line"])
+                if p not in params_blacklist.get(func["name"], []):
+                    print >> sys.stderr, "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):
         if not func:
             return func
-        func["name"] = self.normalizeText(func["name"])
+        fnname = func["name"]
+        fnname = self.normalizeText(fnname)
+        fnname = re.sub(r'_\?D$', "_nD", fnname)  # tailing _?D can be mapped to _nD
+        fnname = re.sub(r'\?D$', "ND", fnname)  # tailing ?D can be mapped to ND
+        fnname = re.sub(r'\(s\)$', "s", fnname) # tailing (s) can be mapped to s
+        func["name"] = fnname
         if "method" in func:
             func["method"] = self.normalizeText(func["method"])
         if "class" in func:
@@ -416,6 +454,11 @@ class RstParser(object):
                 cmt = self.normalizeText(comment)
                 if cmt:
                     params[name] = cmt
+            # expand some wellknown params
+            pmap = params_mapping.get(fnname)
+            if pmap:
+                for name, alias in pmap.items():
+                    params[name] = params[alias]
             func["params"] = params
         if "seealso" in func:
             seealso = []
@@ -450,7 +493,7 @@ class RstParser(object):
                 func["name"] = fname[4:]
                 func["method"] = fname[4:]
             elif show_warnings:
-                print >> sys.stderr, "RST parser warning: invalid definition of old C function \"%s\" - section name is \"%s\" instead of \"%s\". File: %s (line %s)" % (fname, func["name"], fname[6:], func["file"], func["line"])
+                print >> sys.stderr, "\"%s\" - section name is \"%s\" instead of \"%s\". File: %s (line %s)" % (fname, func["name"], fname[6:], func["file"], func["line"])
                 #self.print_info(func)
                 
     def normalizeText(self, s):