Skip to content

O
opencv
Commit ec866c5a authored by Andrey Kamaev's avatar Andrey Kamaev
Browse files
Options

Improved rst_parser and javadoc generation scripts

parent dfe7708f
Hide whitespace changes
Inline Side-by-side
Showing with 180 additions and 137 deletions
modules/java/gen_javadoc.py
View file @ ec866c5a
import os, sys, re, string, glob import os, sys, re, string, glob
allmodules = ["core", "flann", "imgproc", "ml", "highgui", "video", "features2d", "calib3d", "objdetect", "legacy", "contrib", "gpu", "androidcamera", "haartraining", "java", "python", "stitching", "traincascade", "ts"]
javadoc_marker = "//javadoc:" verbose = False
show_warnings = True
def parceJavadocMarker(line): show_errors = True
assert line.lstrip().startswith(javadoc_marker)
offset = line[:line.find(javadoc_marker)] class JavadocGenerator(object):
line = line.strip()[len(javadoc_marker):] def __init__(self, definitions = {}, javadoc_marker = "//javadoc:"):
args_start = line.rfind("(") self.definitions = definitions
args_end = line.rfind(")") self.javadoc_marker = javadoc_marker
assert args_start * args_end > 0 self.markers_processed = 0
if args_start >= 0: self.markers_documented = 0
assert args_start < args_end self.params_documented = 0
return (line[:args_start].strip(), offset, filter(None, list(arg.strip() for arg in line[args_start+1:args_end].split(",")))) self.params_undocumented = 0
return (line, offset, [])
def parceJavadocMarker(self, line):
def document(infile, outfile, decls): assert line.lstrip().startswith(self.javadoc_marker)
inf = open(infile, "rt") offset = line[:line.find(self.javadoc_marker)]
outf = open(outfile, "wt") line = line.strip()[len(self.javadoc_marker):]
try: args_start = line.rfind("(")
for l in inf.readlines(): args_end = line.rfind(")")
if l.lstrip().startswith(javadoc_marker): assert args_start * args_end > 0
marker = parceJavadocMarker(l) if args_start >= 0:
decl = decls.get(marker[0],None) assert args_start < args_end
if decl: return (line[:args_start].strip(), offset, filter(None, list(arg.strip() for arg in line[args_start+1:args_end].split(","))))
for line in makeJavadoc(decl, decls, marker[2]).split("\n"): return (line, offset, [])
outf.write(marker[1] + line + "\n")
def document(self, infile, outfile):
inf = open(infile, "rt")
outf = open(outfile, "wt")
module = os.path.splitext(os.path.basename(infile))[0]
if module not in allmodules:
module = "unknown"
try:
for l in inf.readlines():
if l.lstrip().startswith(self.javadoc_marker):
marker = self.parceJavadocMarker(l)
self.markers_processed += 1
decl = self.definitions.get(marker[0],None)
if decl:
javadoc = self.makeJavadoc(decl, marker[2])
if verbose:
print
print "Javadoc for \"%s\" File: %s (line %s)" % (decl["name"], decl["file"], decl["line"])
print javadoc
for line in javadoc.split("\n"):
outf.write(marker[1] + line + "\n")
self.markers_documented += 1
elif show_errors:
print >> sys.stderr, "gen_javadoc error: could not find documentation for %s (module: %s)" % (l.lstrip()[len(self.javadoc_marker):-1].strip(), module)
else: else:
print "Error: could not find documentation for %s" % l.lstrip()[len(javadoc_marker):-1] outf.write(l.replace("\t", " ").rstrip()+"\n")
else: except:
outf.write(l.replace("\t", " ").rstrip()+"\n") inf.close()
except: outf.close()
inf.close() os.remove(outfile)
outf.close() raise
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: else:
pos_start = 0 inf.close()
pos_end = min(77, len(term)-1) outf.close()
while pos_start < pos_end:
if pos_end - pos_start == 77: def ReformatForJavadoc(self, s):
while pos_end >= pos_start+60: out = ""
if not term[pos_end].isspace(): for term in s.split("\n"):
pos_end -= 1 if term.startswith("*") or term.startswith("#."):
else: term = " " + term
break if not term:
if pos_end < pos_start+60: out += " *\n"
pos_end = min(pos_start + 77, len(term)-1) else:
while pos_end < len(term): 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+60:
if not term[pos_end].isspace(): if not term[pos_end].isspace():
pos_end += 1 pos_end -= 1
else: else:
break break
out += " * " + term[pos_start:pos_end+1].rstrip() + "\n" if pos_end < pos_start+60:
pos_start = pos_end + 1 pos_end = min(pos_start + 77, len(term)-1)
pos_end = min(pos_start + 77, len(term)-1) while pos_end < len(term):
return out if not term[pos_end].isspace():
pos_end += 1
def getJavaName(decl): else:
name = "org.opencv." break
name += decl["module"] out += " * " + term[pos_start:pos_end+1].rstrip() + "\n"
if "class" in decl: pos_start = pos_end + 1
name += "." + decl["class"] pos_end = min(pos_start + 77, len(term)-1)
else: return out
name += "." + decl["module"].capitalize()
if "method" in decl: def getJavaName(self, decl):
name += "." + decl["method"] name = "org.opencv."
return name name += decl["module"]
if "class" in decl:
def getDocURL(decl): name += "." + decl["class"]
url = "http://opencv.itseez.com/modules/" else:
url += decl["module"] name += "." + decl["module"].capitalize()
url += "/doc/" if "method" in decl:
url += os.path.basename(decl["file"]).replace(".rst",".html") name += "." + decl["method"]
url += "#" + decl["name"].replace("::","-").replace("()","").replace("=","").strip().rstrip("_").replace(" ","-").replace("_","-").lower() return name
return url
def getDocURL(self, decl):
def makeJavadoc(decl, decls, args = None): url = "http://opencv.itseez.com/modules/"
doc = "" url += decl["module"]
prefix = "/**\n" url += "/doc/"
url += os.path.basename(decl["file"]).replace(".rst",".html")
if decl.get("isclass", False): url += "#" + decl["name"].replace("::","-").replace("()","").replace("=","").strip().rstrip("_").replace(" ","-").replace("_","-").lower()
decl_type = "class" return url
elif decl.get("isstruct", False):
decl_type = "struct" def makeJavadoc(self, decl, args = None):
elif "class" in decl: doc = ""
decl_type = "method" prefix = "/**\n"
else:
decl_type = "function" if decl.get("isclass", False):
decl_type = "class"
# brief goes first elif decl.get("isstruct", False):
if "brief" in decl: decl_type = "struct"
doc += prefix + ReformatForJavadoc(decl["brief"]) elif "class" in decl:
prefix = " *\n" decl_type = "method"
elif "long" not in decl: else:
print "Warning: no description for " + decl_type + " \"%s\" File: %s (line %s)" % (func["name"], func["file"], func["line"]) decl_type = "function"
doc += prefix + ReformatForJavadoc("This " + decl_type + " is undocumented")
prefix = " *\n" # brief goes first
if "brief" in decl:
doc += prefix + self.ReformatForJavadoc(decl["brief"])
prefix = " *\n"
elif "long" not in decl:
if show_warnings:
print >> sys.stderr, "gen_javadoc warning: no description for " + decl_type + " \"%s\" File: %s (line %s)" % (func["name"], func["file"], func["line"])
doc += prefix + self.ReformatForJavadoc("This " + decl_type + " is undocumented")
prefix = " *\n"
# long goes after brief # long goes after brief
if "long" in decl: if "long" in decl:
doc += prefix + ReformatForJavadoc(decl["long"]) doc += prefix + self.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
if show_warnings:
print >> sys.stderr, "gen_javadoc warning: parameter \"%s\" of \"%s\" is undocumented. File: %s (line %s)" % (arg, decl["name"], decl["file"], decl["line"])
self.params_undocumented += 1
else:
self.params_documented += 1
doc += prefix + self.ReformatForJavadoc("@param " + arg + " " + arg_doc)
prefix = ""
prefix = " *\n"
# @see tags
# always link to documentation
doc += prefix + " * @see <a href=\"" + self.getDocURL(decl) + "\">" + self.getJavaName(decl) + "</a>\n"
prefix = ""
# other links
if "seealso" in decl:
for see in decl["seealso"]:
seedecl = self.definitions.get(see,None)
if seedecl:
doc += prefix + " * @see " + self.getJavaName(seedecl) + "\n"
else:
doc += prefix + " * @see " + see.replace("::",".") + "\n"
prefix = " *\n" prefix = " *\n"
# @param tags #doc += prefix + " * File: " + decl["file"] + " (line " + str(decl["line"]) + ")\n"
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 return (doc + " */").replace("::",".")
# 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"]:
seedecl = decls.get(see,None)
if seedecl:
doc += prefix + " * @see " + getJavaName(seedecl) + "\n"
else:
doc += prefix + " * @see " + see.replace("::",".") + "\n"
prefix = " *\n"
#doc += prefix + " * File: " + decl["file"] + " (line " + str(decl["line"]) + ")\n" def printSummary(self):
print
print "Javadoc Generator Summary:"
print " Total markers: %s" % self.markers_processed
print " Undocumented markers: %s" % (self.markers_processed - self.markers_documented)
print " Generated comments: %s" % self.markers_documented
return (doc + " */").replace("::",".") print
print " Documented params: %s" % self.params_documented
print " Undocumented params: %s" % self.params_undocumented
print
if __name__ == "__main__": if __name__ == "__main__":
if len(sys.argv) < 2: if len(sys.argv) < 2:
...@@ -156,16 +194,19 @@ if __name__ == "__main__": ...@@ -156,16 +194,19 @@ if __name__ == "__main__":
import hdr_parser import hdr_parser
import rst_parser import rst_parser
parser = rst_parser.RstParser(hdr_parser.CppHeaderParser())
print "Parsing documentation..." 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 = rst_parser.RstParser(hdr_parser.CppHeaderParser())
for m in allmodules:
parser.parse(m, os.path.join(selfpath, "../" + m)) parser.parse(m, os.path.join(selfpath, "../" + m))
parser.printSummary() parser.printSummary()
print "Generating javadoc comments..."
generator = JavadocGenerator(parser.definitions)
for i in range(1, len(sys.argv)): for i in range(1, len(sys.argv)):
folder = os.path.abspath(sys.argv[i]) folder = os.path.abspath(sys.argv[i])
for jfile in [f for f in glob.glob(os.path.join(folder,"*.java")) if not f.endswith("-jdoc.java")]: for jfile in [f for f in glob.glob(os.path.join(folder,"*.java")) if not f.endswith("-jdoc.java")]:
outfile = os.path.abspath(os.path.basename(jfile).replace(".java", "-jdoc.java")) outfile = os.path.abspath(os.path.basename(jfile).replace(".java", "-jdoc.java"))
document(jfile, outfile, parser.definitions) generator.document(jfile, outfile)
generator.printSummary()
modules/java/rst_parser.py
View file @ ec866c5a
import os, sys, re, string, glob import os, sys, re, string, glob
allmodules = ["core", "flann", "imgproc", "ml", "highgui", "video", "features2d", "calib3d", "objdetect", "legacy", "contrib", "gpu", "androidcamera", "haartraining", "java", "python", "stitching", "traincascade", "ts"]
verbose = False verbose = False
show_warnings = True show_warnings = True
show_errors = True show_errors = True
...@@ -564,6 +565,7 @@ class RstParser(object): ...@@ -564,6 +565,7 @@ class RstParser(object):
print " structs documented: %s" % structs print " structs documented: %s" % structs
for lang in sorted(stat.items()): for lang in sorted(stat.items()):
print " %7s functions documented: %s" % lang print " %7s functions documented: %s" % lang
print
def mathReplace2(match): def mathReplace2(match):
m = mathReplace(match) m = mathReplace(match)
...@@ -670,7 +672,7 @@ if __name__ == "__main__": ...@@ -670,7 +672,7 @@ if __name__ == "__main__":
parser = RstParser(hdr_parser.CppHeaderParser()) parser = RstParser(hdr_parser.CppHeaderParser())
if module == "all": if module == "all":
for m in ["core", "flann", "imgproc", "ml", "highgui", "video", "features2d", "calib3d", "objdetect", "legacy", "contrib", "gpu", "androidcamera", "haartraining", "java", "python", "stitching", "traincascade", "ts"]: for m in allmodules:
parser.parse(m, os.path.join(rst_parser_dir, "../" + m)) parser.parse(m, os.path.join(rst_parser_dir, "../" + m))
else: else:
parser.parse(module, os.path.join(rst_parser_dir, "../" + module)) parser.parse(module, os.path.join(rst_parser_dir, "../" + module))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment