Fix how the IDL parser handles comments, and fix the chrome.alarms docs.

This includes some other doc improvements that result from the parser
improvement, some unrelated doc changes that just hadn't been
regenerated, and a change to cpp_type_generator.py to actually sort
forward declarations, so the test isn't broken by unrelated changes.

BUG=122817
TEST=Viewed docs in browser.

Review URL: https://chromiumcodereview.appspot.com/10577025
Patch from Jeffrey Yasskin <jyasskin@chromium.org>.

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@143049 0039d316-1c4b-4281-b951-d872f2087c98

5 files changed, 58 insertions, 11 deletions

diff --git a/tools/json_schema_compiler/cpp_type_generator.py b/tools/json_schema_compiler/cpp_type_generator.py
index 1de8d16..55cb36e 100644
--- a/tools/json_schema_compiler/cpp_type_generator.py
+++ b/tools/json_schema_compiler/cpp_type_generator.py
@@ -180,9 +180,12 @@ class CppTypeGenerator(object):
     self._root_namespace.
     """
     c = Code()
-    for namespace, types in sorted(self._NamespaceTypeDependencies().items()):
+    namespace_type_dependencies = self._NamespaceTypeDependencies()
+    for namespace in sorted(namespace_type_dependencies.keys(),
+                            key=lambda ns: ns.name):
       c.Append('namespace %s {' % namespace.name)
-      for type_ in types:
+      for type_ in sorted(namespace_type_dependencies[namespace],
+                          key=schema_util.StripSchemaNamespace):
         type_name = schema_util.StripSchemaNamespace(type_)
         if namespace.types[type_].type_ == PropertyType.STRING:
           c.Append('typedef std::string %s;' % type_name)
diff --git a/tools/json_schema_compiler/cpp_type_generator_test.py b/tools/json_schema_compiler/cpp_type_generator_test.py
index 70d3e74..b22c430 100755
--- a/tools/json_schema_compiler/cpp_type_generator_test.py
+++ b/tools/json_schema_compiler/cpp_type_generator_test.py
@@ -71,8 +71,8 @@ class CppTypeGeneratorTest(unittest.TestCase):
         manager.GenerateIncludes().Render())
     self.assertEquals(
         'namespace tabs {\n'
-        'struct Tab;\n'
         'struct Permissions;\n'
+        'struct Tab;\n'
         '}\n'
         'namespace windows {\n'
         'struct Window;\n'
diff --git a/tools/json_schema_compiler/idl_schema.py b/tools/json_schema_compiler/idl_schema.py
index 28f2a3b..5adfc1f 100644
--- a/tools/json_schema_compiler/idl_schema.py
+++ b/tools/json_schema_compiler/idl_schema.py
@@ -3,6 +3,7 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+import itertools
 import json
 import os.path
 import re
@@ -27,8 +28,21 @@ import idl_parser
 
 def ProcessComment(comment):
   '''
-  Given the string from a Comment node, parse it into a tuple that looks
-  like:
+  Convert a comment into a parent comment and a list of parameter comments.
+
+  Function comments are of the form:
+    Function documentation. May contain HTML and multiple lines.
+
+    |arg1_name|: Description of arg1. Use <var>argument</var> to refer
+    to other arguments.
+    |arg2_name|: Description of arg2...
+
+  Newlines are removed, and leading and trailing whitespace is stripped.
+
+  Args:
+    comment: The string from a Comment node.
+
+  Returns: A tuple that looks like:
     (
       "The processed comment, minus all |parameter| mentions.",
       {
@@ -38,15 +52,26 @@ def ProcessComment(comment):
     )
   '''
   # Find all the parameter comments of the form "|name|: comment".
-  parameter_comments = re.findall(r'\n *\|([^|]*)\| *: *(.*)', comment)
+  parameter_starts = list(re.finditer(r'\n *\|([^|]*)\| *: *', comment))
+
   # Get the parent comment (everything before the first parameter comment.
-  parent_comment = re.sub(r'\n *\|.*', '', comment)
+  first_parameter_location = (parameter_starts[0].start()
+                              if parameter_starts else len(comment))
+  parent_comment = comment[:first_parameter_location]
   parent_comment = parent_comment.replace('\n', '').strip()
 
-  parsed = {}
-  for (name, comment) in parameter_comments:
-    parsed[name] = comment.replace('\n', '').strip()
-  return (parent_comment, parsed)
+  params = {}
+  for (cur_param, next_param) in itertools.izip_longest(parameter_starts,
+                                                        parameter_starts[1:]):
+    param_name = cur_param.group(1)
+
+    # A parameter's comment goes from the end of its introduction to the
+    # beginning of the next parameter's introduction.
+    param_comment_start = cur_param.end()
+    param_comment_end = next_param.start() if next_param else len(comment)
+    params[param_name] = comment[param_comment_start:param_comment_end
+                                 ].replace('\n', '').strip()
+  return (parent_comment, params)
 
 class Callspec(object):
   '''
diff --git a/tools/json_schema_compiler/idl_schema_test.py b/tools/json_schema_compiler/idl_schema_test.py
index 5a941e0..d594de5 100755
--- a/tools/json_schema_compiler/idl_schema_test.py
+++ b/tools/json_schema_compiler/idl_schema_test.py
@@ -77,5 +77,18 @@ class IdlSchemaTest(unittest.TestCase):
     self.assertTrue(func is not None)
     self.assertTrue(func['nocompile'])
 
+  def testFunctionComment(self):
+    schema = self.idl_basics
+    func = getFunction(schema, 'function3')
+    self.assertEquals(('This comment should appear in the documentation, '
+                       'despite occupying multiple lines.'),
+                      func['description'])
+    self.assertEquals(
+        [{'description': ('So should this comment about the argument. '
+                          '<em>HTML</em> is fine too.'),
+          'name': 'arg',
+          '$ref': 'idl_basics.MyType1'}],
+        func['parameters'])
+
 if __name__ == '__main__':
   unittest.main()
diff --git a/tools/json_schema_compiler/test/idl_basics.idl b/tools/json_schema_compiler/test/idl_basics.idl
index d85b5e2e..e2ccd07 100644
--- a/tools/json_schema_compiler/test/idl_basics.idl
+++ b/tools/json_schema_compiler/test/idl_basics.idl
@@ -28,6 +28,12 @@ namespace idl_basics {
   interface Functions {
     static void function1();
     static void function2(long x);
+    // This comment should appear in the documentation,
+    // despite occupying multiple lines.
+    //
+    // |arg|: So should this comment
+    // about the argument.
+    // <em>HTML</em> is fine too.
     static void function3(MyType1 arg);
 
     static void function4(Callback1 cb);