From 5c01d13f38c7826e5d03ea9944a818c8c9937126 Mon Sep 17 00:00:00 2001 From: Andrey Kamaev Date: Mon, 27 Aug 2012 16:48:09 +0400 Subject: [PATCH] Pass list of modules to javadoc generator Previously the generator always uses hardcoded list of modules. This fix replaces hardcoded list with actual set of modules coming from cmake. --- modules/java/CMakeLists.txt | 4 +- modules/java/generator/gen_javadoc.py | 59 +++++++++++++++++---------- 2 files changed, 39 insertions(+), 24 deletions(-) diff --git a/modules/java/CMakeLists.txt b/modules/java/CMakeLists.txt index 86c77b88d2..39c90d354d 100644 --- a/modules/java/CMakeLists.txt +++ b/modules/java/CMakeLists.txt @@ -108,10 +108,10 @@ file(GLOB_RECURSE refman_rst_headers "${CMAKE_CURRENT_SOURCE_DIR}/../*.rst") set(java_documented_headers_deps ${handwrittren_java_sources} ${generated_java_sources} ${java_hdr_deps} ${refman_rst_headers} "${GEN_JAVADOC}" "${RST_PARSER}" "${GEN_JAVA}" "${HDR_PARSER}") -#TODO: pass list of modules +string(REPLACE ";" "," OPENCV_JAVA_MODULES_STR "${OPENCV_JAVA_MODULES}") add_custom_command( OUTPUT ${documented_java_files} - COMMAND ${PYTHON_EXECUTABLE} "${GEN_JAVADOC}" "${CMAKE_CURRENT_SOURCE_DIR}/generator/src/java" "${CMAKE_CURRENT_BINARY_DIR}" 2>"${CMAKE_CURRENT_BINARY_DIR}/get_javadoc_errors.log" + COMMAND ${PYTHON_EXECUTABLE} "${GEN_JAVADOC}" --modules ${OPENCV_JAVA_MODULES_STR} "${CMAKE_CURRENT_SOURCE_DIR}/generator/src/java" "${CMAKE_CURRENT_BINARY_DIR}" 2>"${CMAKE_CURRENT_BINARY_DIR}/get_javadoc_errors.log" WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} DEPENDS ${java_documented_headers_deps} ) diff --git a/modules/java/generator/gen_javadoc.py b/modules/java/generator/gen_javadoc.py index 5d4c5cfd8b..ecf6f3c55e 100644 --- a/modules/java/generator/gen_javadoc.py +++ b/modules/java/generator/gen_javadoc.py @@ -1,17 +1,18 @@ 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", "photo", "videostab"] -verbose = False -show_warnings = True -show_errors = True +from optparse import OptionParser class JavadocGenerator(object): - def __init__(self, definitions = {}, javadoc_marker = "//javadoc:"): + def __init__(self, definitions = {}, modules= [], javadoc_marker = "//javadoc:"): self.definitions = definitions self.javadoc_marker = javadoc_marker self.markers_processed = 0 self.markers_documented = 0 self.params_documented = 0 self.params_undocumented = 0 + self.known_modules = modules + self.verbose = False + self.show_warnings = True + self.show_errors = True def parceJavadocMarker(self, line): assert line.lstrip().startswith(self.javadoc_marker) @@ -35,7 +36,7 @@ class JavadocGenerator(object): inf = open(infile, "rt") outf = open(outfile, "wt") module = os.path.splitext(os.path.basename(infile))[0].split("+")[0] - if module not in allmodules: + if module not in self.known_modules: module = "unknown" try: for l in inf.readlines(): @@ -47,14 +48,14 @@ class JavadocGenerator(object): decl = self.definitions.get(marker[0],None) if decl: javadoc = self.makeJavadoc(decl, marker[2]) - if verbose: + if self.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: + elif self.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: outf.write(org.replace("\t", " ").rstrip()+"\n") @@ -176,11 +177,11 @@ class JavadocGenerator(object): doc += prefix + self.ReformatForJavadoc(decl["brief"]) prefix = " *\n" elif "long" not in decl: - if show_warnings: + if self.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 if "long" in decl: doc += prefix + self.ReformatForJavadoc(decl["long"]) @@ -193,7 +194,7 @@ class JavadocGenerator(object): arg_doc = documented_params.get(arg, None) if not arg_doc: arg_doc = "a " + arg - if show_warnings: + if self.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: @@ -233,29 +234,43 @@ class JavadocGenerator(object): print if __name__ == "__main__": - if len(sys.argv) < 2: - print "Usage:\n", os.path.basename(sys.argv[0]), " [ [...]]" - 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 = OptionParser() + parser.add_option("-v", "--verbose", dest="verbose", help="Print verbose log to stdout", action="store_true", default=False) + parser.add_option("", "--no-warnings", dest="warnings", help="Hide warning messages", action="store_false", default=True) + parser.add_option("", "--no-errors", dest="errors", help="Hide error messages", action="store_false", default=True) + parser.add_option("", "--modules", dest="modules", help="comma-separated list of modules to generate comments", metavar="MODS", default=",".join(rst_parser.allmodules)) + + (options, args) = parser.parse_args(sys.argv) + options.modules = options.modules.split(",") + + if len(args) < 2 or len(options.modules) < 1: + parser.print_help() + exit(0) + print "Parsing documentation..." parser = rst_parser.RstParser(hdr_parser.CppHeaderParser()) - for m in allmodules: + for m in options.modules: parser.parse(m, os.path.join(selfpath, "../../" + m)) - + parser.printSummary() - print "Generating javadoc comments..." - generator = JavadocGenerator(parser.definitions) - for i in range(1, len(sys.argv)): - folder = os.path.abspath(sys.argv[i]) + generator = JavadocGenerator(parser.definitions, options.modules) + generator.verbose = options.verbose + generator.show_warnings = options.warnings + generator.show_errors = options.errors + + print "Generating javadoc comments for " + ", ".join(options.modules) + for path in args: + folder = os.path.abspath(path) 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")) generator.document(jfile, outfile)