Hack together a quick doc generator for IDL files.

tools/json_schema_compiler/idl_schema.py

 #! /usr/bin/env python
 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 import json
 import os.path
 import sys
+import re
 
 # This file is a peer to json_schema.py. Each of these files understands a
 # certain format describing APIs (either JSON or IDL), reads files written
 # in that format into memory, and emits them as a Python array of objects
 # corresponding to those APIs, where the objects are formatted in a way that
 # the JSON schema compiler understands. compiler.py drives both idl_schema.py
 # and json_schema.py.
 
 # idl_parser expects to be able to import certain files in its directory,
 # so let's set things up the way it wants.
 idl_generators_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),
                                   os.pardir, os.pardir, 'ppapi', 'generators')
 if idl_generators_path not in sys.path:
   sys.path.insert(0, idl_generators_path)
 import idl_parser
 
+def ProcessComment(comment):
+  '''
+  Given the string from a Comment node, parse it into a tuple that looks
+  like:
+    (
+      "The processed comment, minus all |parameter| mentions.",
+      {
+        'parameter_name_1': "The comment that followed |parameter_name_1|:",
+        ...
+      }
+    )
+  '''
+  # Find all the parameter comments of the form "|name|: comment".
+  parameter_comments = re.findall(r'\n *\|([^|]*)\| *: *(.*)', comment)
+  # Get the parent comment (everything before the first parameter comment.
+  parent_comment = re.sub(r'\n *\|.*', '', comment)
+  parent_comment = parent_comment.replace('\n', '').strip()
+
+  parsed = {}
+  for (name, comment) in parameter_comments:
+    parsed[name] = comment.replace('\n', '').strip()
+  return (parent_comment, parsed)
+
 class Callspec(object):
   '''
   Given a Callspec node representing an IDL function declaration, converts into
   a name/value pair where the value is a list of function parameters.
   '''
-  def __init__(self, callspec_node):
+  def __init__(self, callspec_node, comment):
     self.node = callspec_node
+    self.comment = comment
 
   def process(self, callbacks):
     parameters = []
     for node in self.node.children:
-      parameters.append(Param(node).process(callbacks))
+      parameter = Param(node).process(callbacks)
+      if parameter['name'] in self.comment:
+        parameter['description'] = self.comment[parameter['name']]
+      parameters.append(parameter)
     return self.node.GetName(), parameters
 
 class Param(object):
   '''
   Given a Param node representing a function parameter, converts into a Python
   dictionary that the JSON schema compiler expects to see.
   '''
   def __init__(self, param_node):
     self.node = param_node
 
@@ skipping 30 matching lines @@
     self.node = member_node
 
   def process(self, callbacks):
     properties = {}
     name = self.node.GetName()
     if self.node.GetProperty('OPTIONAL'):
       properties['optional'] = True
     if self.node.GetProperty('nodoc'):
       properties['nodoc'] = True
     is_function = False
+    parameter_comments = {}
+    for node in self.node.children:
+      if node.cls == 'Comment':
+        (parent_comment, parameter_comments) = ProcessComment(node.GetName())
+        properties['description'] = parent_comment
     for node in self.node.children:
       if node.cls == 'Callspec':
         is_function = True
-        name, parameters = Callspec(node).process(callbacks)
+        name, parameters = Callspec(node, parameter_comments).process(callbacks)
         properties['parameters'] = parameters
     properties['name'] = name
     if is_function:
       properties['type'] = 'function'
     else:
       properties = Typeref(self.node.GetProperty('TYPEREF'),
                            self.node, properties).process(callbacks)
     return name, properties
 
 class Typeref(object):
@@ skipping 140 matching lines @@
   '''
   Dump a json serialization of parse result for the IDL files whose names
   were passed in on the command line.
   '''
   for filename in sys.argv[1:]:
     schema = Load(filename)
     print json.dumps(schema, indent=2)
 
 if __name__ == '__main__':
   Main()