Chiebot-Mirror
/
opencv
mirror of https://github.com/opencv/opencv.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improved rst_parser and javadoc generation scripts

Browse Source
pull/13383/head
Andrey Kamaev 14 years ago
parent dfe7708f17
commit ec866c5acd
2 changed files with 180 additions and 137 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 313
      modules/java/gen_javadoc.py
  2. 4
      modules/java/rst_parser.py

313
modules/java/gen_javadoc.py
Unescape View File

@ -1,147 +1,185 @@
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__":
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()

4
modules/java/rst_parser.py
Unescape View File

@ -1,4 +1,5 @@
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):
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__":
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))

Write Preview
Loading…
Cancel
Save