Improved rst_parser; added javadoc comments generator; added javadoc markers to…

Improved rst_parser; added javadoc comments generator; added javadoc markers to handwritten .java files

modules/java/gen_javadoc.py

+import os, sys, re, string, glob
+
+javadoc_marker = "//javadoc:"
+
+def parceJavadocMarker(line):
+    assert line.lstrip().startswith(javadoc_marker)
+    offset = line[:line.find(javadoc_marker)]
+    line = line.strip()[len(javadoc_marker):]
+    args_start = line.rfind("(")
+    args_end = line.rfind(")")
+    assert args_start * args_end > 0
+    if args_start >= 0:
+        assert args_start < args_end
+        return (line[:args_start].strip(), offset,  filter(None, list(arg.strip() for arg in line[args_start+1:args_end].split(","))))
+    return (line, offset, [])
+
+def document(infile, outfile, decls):
+    inf = open(infile, "rt")
+    outf = open(outfile, "wt")
+    try:
+        for l in inf.readlines():
+            if l.lstrip().startswith(javadoc_marker):
+                marker = parceJavadocMarker(l)
+                decl = decls.get(marker[0],None)
+                if decl:
+                    for line in makeJavadoc(decl, marker[2]).split("\n"):
+                        outf.write(marker[1] + line + "\n")
+                else:
+                    print "Error: could not find documentation for %s" % l.lstrip()[len(javadoc_marker):-1]
+            else:
+                outf.write(l.replace("\t", "    ").rstrip()+"\n")
+    except:
+        inf.close()
+        outf.close()
+        os.remove(outfile)
+        raise
+    else:
+        inf.close()
+        outf.close()
+
+def ReformatForJavadoc(s):
+    out = ""
+    for term in s.split("\n"):
+        if term.startswith("*") or term.startswith("#."):
+            term = "  " + term
+        if not term:
+            out += " *\n"
+        else:
+            pos_start = 0
+            pos_end = min(77, len(term)-1)
+            while pos_start < pos_end:
+                if pos_end - pos_start == 77:
+                    while pos_end >= pos_start:
+                        if not term[pos_end].isspace():
+                            pos_end -= 1
+                        else:
+                            break
+                    if pos_end < pos_start:
+                        pos_end = min(pos_start + 77, len(term)-1)
+                        while pos_end < len(term):
+                            if not term[pos_end].isspace():
+                                pos_end += 1
+                            else:
+                                break
+                out += " * " + term[pos_start:pos_end+1].rstrip() + "\n"
+                pos_start = pos_end + 1
+                pos_end = min(pos_start + 77, len(term)-1)
+    return out
+
+def getJavaName(decl):
+    name = "org.opencv."
+    name += decl["module"]
+    if "class" in decl:
+        name += "." + decl["class"]
+    if "method" in decl:
+        name += "." + decl["method"]
+    return name
+
+def getDocURL(decl):
+    url = "http://opencv.itseez.com/modules/"
+    url += decl["module"]
+    url += "/doc/"
+    url += os.path.basename(decl["file"]).replace(".rst",".html")
+    url += "#" + decl["name"].replace("::","-").replace("()","").replace("=","").strip().rstrip("_").replace(" ","-").replace("_","-").lower()
+    return url
+
+def makeJavadoc(decl, args = None): 
+    doc = ""
+    prefix = "/**\n"
+
+    if decl.get("isclass", False):
+        decl_type = "class"
+    elif decl.get("isstruct", False):
+        decl_type = "struct"
+    elif "class" in decl:
+        decl_type = "method"
+    else:
+        decl_type = "function"
+
+    # brief goes first
+    if "brief" in decl:
+        doc += prefix + ReformatForJavadoc(decl["brief"])
+        prefix = " *\n"
+    elif "long" not in decl:
+        print "Warning: no description for " + decl_type + " \"%s\" File: %s (line %s)" % (func["name"], func["file"], func["line"])
+        doc += prefix + ReformatForJavadoc("This " + decl_type + " is undocumented")
+        prefix = " *\n"
+    
+    # long goes after brief
+    if "long" in decl:
+        doc += prefix  + ReformatForJavadoc(decl["long"])
+        prefix = " *\n"
+
+    # @param tags
+    if args and (decl_type == "method" or decl_type == "function"):
+        documented_params = decl.get("params",{})
+        for arg in args:
+            arg_doc = documented_params.get(arg, None)
+            if not arg_doc:
+                arg_doc = "a " + arg
+                print "Warning: parameter \"%s\" of \"%s\" is undocumented. File: %s (line %s)" % (arg, decl["name"], decl["file"], decl["line"])
+            doc += prefix + ReformatForJavadoc("@param " + arg + " " + arg_doc)
+            prefix = ""
+        prefix = " *\n"
+
+    # @see tags
+    # always link to documentation
+    doc += prefix + " * @see <a href=\"" + getDocURL(decl) + "\">" + getJavaName(decl) + "</a>\n"
+    prefix = ""
+    # other links
+    if "seealso" in decl:
+        for see in decl["seealso"]:
+            doc += prefix + " * @see " + see.replace("::",".") + "\n"
+    prefix = " *\n"
+
+    #doc += prefix + " * File: " + decl["file"] + " (line " + str(decl["line"]) + ")\n"
+
+    return (doc + " */").replace("::",".")
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print "Usage:\n", os.path.basename(sys.argv[0]), " <input dir1> [<input dir2> [...]]"
+        exit(0)
+   
+    selfpath = os.path.dirname(os.path.abspath(sys.argv[0]))
+    hdr_parser_path = os.path.join(selfpath, "../python/src2")
+    
+    sys.path.append(selfpath)
+    sys.path.append(hdr_parser_path)
+    import hdr_parser
+    import rst_parser
+
+    parser = rst_parser.RstParser(hdr_parser.CppHeaderParser())
+    
+    print "Parsing documentation..."
+    for m in ["core", "flann", "imgproc", "ml", "highgui", "video", "features2d", "calib3d", "objdetect", "legacy", "contrib", "gpu", "androidcamera", "haartraining", "java", "python", "stitching", "traincascade", "ts"]:
+        parser.parse(m, os.path.join(selfpath, "../" + m))
+
+    for i in range(1, len(sys.argv)):
+        folder = os.path.abspath(sys.argv[i])
+        for jfile in glob.glob(os.path.join(folder,"*.java")):
+            outfile = os.path.abspath(os.path.basename(jfile).replace(".java", "-jdoc.java"))
+            document(jfile, outfile, parser.definitions)

modules/java/rst_parser.py

 import os, sys, re, string, glob
-from string import Template
 
 class DeclarationParser(object):
     def __init__(self, line=None):
@@ -445,8 +444,6 @@ class RstParser(object):
             return s
         # normalize line endings
         s = re.sub(r"\r\n", "\n", s)
-        # remove tailing ::
-        s = re.sub(r"::$", "\n", s)
         # remove extra line breaks before/after _ or ,
         s = re.sub(r"\n[ ]*([_,])\n", r"\1 ", s)
         # remove extra line breaks after `
@@ -465,7 +462,7 @@ class RstParser(object):
         # remove extra line breaks after #.
         s = re.sub(r"\n#\.\n+", "\n#. ", s)
         # remove extra line breaks before `
-        s = re.sub(r"\n[ ]*`", " `", s)
+        #s = re.sub(r"\n[ ]*`", " `", s)
         # remove trailing whitespaces
         s = re.sub(r"[ ]+$", "", s)
         # remove .. for references
@@ -485,6 +482,7 @@ class RstParser(object):
 
         s = s.replace("]_", "]")
         s = s.replace(".. note::", "Note:")
+        s = s.replace(".. table::", "")
         s = s.replace(".. ocv:function::", "")
         s = s.replace(".. ocv:cfunction::", "")
 
@@ -492,7 +490,9 @@ class RstParser(object):
         s = re.sub(r"(^|\n)\.\. [a-zA-Z_0-9]+(::[a-zA-Z_0-9]+)?:(\n|$)", "\n ", s)
         # unwrap urls
         s = re.sub(r"`([^`<]+ )<(https?://[^>]+)>`_", "\\1(\\2)", s)
-        
+        # remove tailing ::
+        s = re.sub(r"::$", "\n", s)
+
         # remove whitespace before .
         s = re.sub(r"[ ]+\.", ".", s)
         # remove tailing whitespace
@@ -502,7 +502,7 @@ class RstParser(object):
         # compress line breaks
         s = re.sub(r"\n\n+", "\n\n", s)
         # remove other newlines
-        s = re.sub(r"([^.\n])\n([^*#\n])", "\\1 \\2", s)
+        s = re.sub(r"([^.\n\\=])\n([^*#\n])", "\\1 \\2", s)
         # compress whitespace
         s = re.sub(r" +", " ", s)
 
@@ -518,7 +518,7 @@ class RstParser(object):
         return s
 
 if __name__ == "__main__":
-    if len(sys.argv) < 1:
+    if len(sys.argv) < 2:
         print "Usage:\n", os.path.basename(sys.argv[0]), " <module path>"
         exit(0)
 
@@ -569,4 +569,8 @@ if __name__ == "__main__":
     for lang in sorted(stat.items()):
         print "  %7s functions documented: %s" % lang
 
+#    sys.exit(0)
+ #   for name, d in parser.definitions.items():
+  #      print
+   #     print ToJavadoc(d, d.get("params",{}).keys())
 

modules/java/src/java/Point.java

 package org.opencv;
 
+//javadoc:Point_
 public class Point {
 	
 	public double x, y;

modules/java/src/java/Point3.java

 package org.opencv;
 
+//javadoc:Point3_
 public class Point3 {
 
 	public double x, y, z;

modules/java/src/java/Rect.java

 package org.opencv;
 
+//javadoc:Rect_
 public class Rect {
 	
 	int x, y, width, height;

modules/java/src/java/Scalar.java

 package org.opencv;
 
+//javadoc:Scalar_
 public class Scalar {
 	
 	public double v0, v1, v2, v3;

modules/java/src/java/Size.java

 package org.opencv;
 
+//javadoc:Size_
 public class Size {
 
 	public int width, height;