Hack together a quick doc generator for IDL files.

tools/json_schema_compiler/idl_schema.py

Index: tools/json_schema_compiler/idl_schema.py
diff --git a/tools/json_schema_compiler/idl_schema.py b/tools/json_schema_compiler/idl_schema.py
index 1d3c83ae3b9652767c0f73ec4e56601d8e2b933c..70ed9edb5fa2c967a482cdd20b8d69375c453228 100644
--- a/tools/json_schema_compiler/idl_schema.py
+++ b/tools/json_schema_compiler/idl_schema.py
@@ -4,6 +4,7 @@
 
 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
@@ -20,18 +21,42 @@ 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):
@@ -82,10 +107,15 @@ class Member(object):
     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: