Title: [127475] trunk/Tools
- Revision
- 127475
- Author
- [email protected]
- Date
- 2012-09-04 11:33:10 -0700 (Tue, 04 Sep 2012)
Log Message
[GTK] Print API missing documentation when generating gtkdoc
https://bugs.webkit.org/show_bug.cgi?id=95703
Patch by Martin Robinson <[email protected]> on 2012-09-04
Reviewed by Carlos Garcia Campos.
Print out API missing documentation when generating gtkdoc. This makes it
easier to fix documentation errors.
* gtk/generate-gtkdoc:
(print_missing_api): Added.
(generate_doc): Inline the rebase step, since it now reports an error
when you try to rebase without generating documentation first.
* gtk/gtkdoc.py:
(GTKDoc.rebase_installed_docs): Raise an error when rebasing without
generating documentation first to enable a small cleanup at the caller.
(GTKDoc.api_missing_documentation): Added.
Modified Paths
Diff
Modified: trunk/Tools/ChangeLog (127474 => 127475)
--- trunk/Tools/ChangeLog 2012-09-04 18:31:31 UTC (rev 127474)
+++ trunk/Tools/ChangeLog 2012-09-04 18:33:10 UTC (rev 127475)
@@ -1,3 +1,22 @@
+2012-09-04 Martin Robinson <[email protected]>
+
+ [GTK] Print API missing documentation when generating gtkdoc
+ https://bugs.webkit.org/show_bug.cgi?id=95703
+
+ Reviewed by Carlos Garcia Campos.
+
+ Print out API missing documentation when generating gtkdoc. This makes it
+ easier to fix documentation errors.
+
+ * gtk/generate-gtkdoc:
+ (print_missing_api): Added.
+ (generate_doc): Inline the rebase step, since it now reports an error
+ when you try to rebase without generating documentation first.
+ * gtk/gtkdoc.py:
+ (GTKDoc.rebase_installed_docs): Raise an error when rebasing without
+ generating documentation first to enable a small cleanup at the caller.
+ (GTKDoc.api_missing_documentation): Added.
+
2012-09-04 Vincent Scheib <[email protected]>
[Chromium] Allow asyncronous response of pointer lock requests in layout tests.
Modified: trunk/Tools/gtk/generate-gtkdoc (127474 => 127475)
--- trunk/Tools/gtk/generate-gtkdoc 2012-09-04 18:31:31 UTC (rev 127474)
+++ trunk/Tools/gtk/generate-gtkdoc 2012-09-04 18:33:10 UTC (rev 127475)
@@ -137,18 +137,20 @@
})
return options
-def generate_doc(pkg_config_path, options):
- generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
+def print_missing_api(generator):
+ missing_api = generator.api_missing_documentation()
+ if not missing_api:
+ return
+ print "\nThe following API are missing documentation:"
+ for api in missing_api:
+ print "\t%s" % api
+
+def generate_doc(generator):
generator.generate(html='--skip-html' not in sys.argv)
+ if generator.saw_warnings:
+ print_missing_api(generator)
return generator.saw_warnings
-def rebase_installed_docs(pkg_config_path, options):
- if not os.path.isdir(options['output_dir']):
- print "Documentation was not generated"
- return
- generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
- generator.rebase_installed_docs()
-
configure_logging()
# We need to add the _javascript_Core build directory to the PKG_CONFIG_PATH
@@ -165,22 +167,23 @@
pkg_config_path = common.build_path('Source', 'WebKit', 'gtk', 'webkit-1.0.pc')
if os.path.exists(pkg_config_path):
options = get_webkit1_options(common.gtk_version_of_pkg_config_file(pkg_config_path))
+ generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, options)
if '--rebase' not in sys.argv:
print "Generating WebKit1 documentation..."
- saw_webkit1_warnings = generate_doc(pkg_config_path, options)
+ saw_webkit1_warnings = generate_doc(generator)
else:
print "Rebasing WebKit1 documentation..."
- rebase_installed_docs(pkg_config_path, options)
+ generator.rebase_installed_docs()
# WebKit2 might not be enabled, so check for the pkg-config file before building documentation.
pkg_config_path = common.build_path('Source', 'WebKit2', 'webkit2gtk-3.0.pc')
if os.path.exists(pkg_config_path):
- options = get_webkit2_options()
+ generator = gtkdoc.PkgConfigGTKDoc(pkg_config_path, get_webkit2_options())
if '--rebase' not in sys.argv:
print "\nGenerating WebKit2 documentation..."
- saw_webkit2_warnings = generate_doc(pkg_config_path, options)
+ saw_webkit2_warnings = generate_doc(generator)
else:
print "\nRebasing WebKit2 documentation..."
- rebase_installed_docs(pkg_config_path, options)
+ generator.rebase_installed_docs()
sys.exit(saw_webkit1_warnings or saw_webkit2_warnings)
Modified: trunk/Tools/gtk/gtkdoc.py (127474 => 127475)
--- trunk/Tools/gtk/gtkdoc.py 2012-09-04 18:31:31 UTC (rev 127474)
+++ trunk/Tools/gtk/gtkdoc.py 2012-09-04 18:33:10 UTC (rev 127475)
@@ -361,6 +361,8 @@
self._run_command(args, cwd=self.output_dir, ignore_warnings=True)
def rebase_installed_docs(self):
+ if not os.path.isdir(self.output_dir):
+ raise Exception("Tried to rebase documentation before generating it.")
html_dir = os.path.join(self.virtual_root + self.prefix, 'share', 'gtk-doc', 'html', self.module_name)
if not os.path.isdir(html_dir):
return
@@ -372,6 +374,11 @@
args.extend(['--dest-dir=%s' % self.virtual_root])
self._run_command(args, cwd=self.output_dir)
+ def api_missing_documentation(self):
+ unused_doc_file = os.path.join(self.output_dir, self.module_name + "-unused.txt")
+ if not os.path.exists(unused_doc_file) or not os.access(unused_doc_file, os.R_OK):
+ return []
+ return open(unused_doc_file).read().splitlines()
class PkgConfigGTKDoc(GTKDoc):
_______________________________________________
webkit-changes mailing list
[email protected]
http://lists.webkit.org/mailman/listinfo/webkit-changes
