Changeset 127475 in webkit

Timestamp:

Sep 4, 2012 11:33:10 AM (12 years ago)

Author:

commit-queue@webkit.org

Message:

[GTK] Print API missing documentation when generating gtkdoc
​https://bugs.webkit.org/show_bug.cgi?id=95703

Patch by Martin Robinson <​mrobinson@igalia.com> 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.

Location:

trunk/Tools

Files:

• ChangeLog (modified) (1 diff)
• gtk/generate-gtkdoc (modified) (2 diffs)
• gtk/gtkdoc.py (modified) (2 diffs)

trunk/Tools/ChangeLog

@@ +1 @@
+2012-09-04  Martin Robinson  <mrobinson@igalia.com>
+
+        [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  <scheib@chromium.org>
 

trunk/Tools/gtk/generate-gtkdoc

@@ -138 +138 @@
     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()
@@ -166 +168 @@
 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)

trunk/Tools/gtk/gtkdoc.py

@@ -362 +362 @@
 
     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):
@@ -373 +375 @@
         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):