Hack together a quick doc generator for IDL files.

tools/json_schema_compiler/idl_schema.py

 # 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 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 dictionary that looks
+  like:
+    {
+      '': "The processed comment, minus all |parameter| mentions.",

[asargent_no_longer_on_chrome, 2012/04/16 17:34:11]

nit: using the empty string as a key makes the code a little hard to read. Can
you use something like 'SUMMARY' or 'OVERVIEW' or '_SUMMARY_' instead?

[Matt Perry, 2012/04/16 19:19:15]

I had it return a tuple of (summary_comment, parsed_comments) instead.

+      '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 = {'': parent_comment}
+  for (name, comment) in parameter_comments:
+    parsed[name] = comment.replace('\n', '').strip()
+  return 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, refs):
     parameters = []
     for node in self.node.children:
-      parameters.append(Param(node).process(refs))
+      parameter = Param(node).process(refs)
+      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, refs):
     properties = {}
     name = self.node.GetName()
     if self.node.GetProperty('OPTIONAL'):
       properties['optional'] = True
     if self.node.GetProperty('nodoc'):
       properties['nodoc'] = True
     is_function = False
+    comment = {}
+    for node in self.node.children:
+      if node.cls == 'Comment':
+        comment = ProcessComment(node.GetName())
+        properties['description'] = comment['']
     for node in self.node.children:
       if node.cls == 'Callspec':
         is_function = True
-        name, parameters = Callspec(node).process(refs)
+        name, parameters = Callspec(node, comment).process(refs)
         properties['parameters'] = parameters
     properties['name'] = name
     if is_function:
       properties['type'] = 'function'
     else:
       properties = Typeref(self.node.GetProperty('TYPEREF'),
                            self.node, properties).process(refs)
     return name, properties
 
 class Typeref(object):
@@ skipping 128 matching lines @@
   Python dictionary in a format that the JSON schema compiler expects to see.
   '''
 
   f = open(filename, 'r')
   contents = f.read()
   f.close()
 
   idl = idl_parser.IDLParser().ParseData(contents, filename)
   idl_schema = IDLSchema(idl)
   return idl_schema.process()