Extension docs: Make comments in IDL files generate paragraphs rather than

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 itertools
 import json
 import os.path
 import re
 import sys
@@ skipping 38 matching lines @@
 
   Returns: A tuple that looks like:
     (
       "The processed comment, minus all |parameter| mentions.",
       {
         'parameter_name_1': "The comment that followed |parameter_name_1|:",
         ...
       }
     )
   '''
+  def add_paragraphs(content):
+    paragraphs = content.split('\n\n')
+    if len(paragraphs) < 2:
+      return content
+    return '<p>' + '</p><p>'.join(p.strip() for p in paragraphs) + '</p>'
+
   # Find all the parameter comments of the form '|name|: comment'.
   parameter_starts = list(re.finditer(r' *\|([^|]*)\| *: *', comment))
 
   # Get the parent comment (everything before the first parameter comment.
   first_parameter_location = (parameter_starts[0].start()
                               if parameter_starts else len(comment))
-  parent_comment = comment[:first_parameter_location]
-
-  # We replace \n\n with <br/><br/> here and below, because the documentation
-  # needs to know where the newlines should be, and this is easier than
-  # escaping \n.
-  parent_comment = (parent_comment.strip().replace('\n\n', '<br/><br/>')
-                                          .replace('\n', ''))
+  parent_comment = (add_paragraphs(comment[:first_parameter_location].strip())
+                    .replace('\n', ''))
 
   params = OrderedDict()
   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
-                                  ].strip().replace('\n\n', '<br/><br/>')
-                                           .replace('\n', ''))
+    params[param_name] = (
+        add_paragraphs(comment[param_comment_start:param_comment_end].strip())
+        .replace('\n', ''))
+
   return (parent_comment, params)
 
 
 class Callspec(object):
   '''
   Given a Callspec node representing an IDL function declaration, converts into
   a tuple:
       (name, list of function parameters, return type)
   '''
   def __init__(self, callspec_node, comment):
@@ skipping 382 matching lines @@
       print json.dumps(schema, indent=2)
   else:
     contents = sys.stdin.read()
     idl = idl_parser.IDLParser().ParseData(contents, '<stdin>')
     schema = IDLSchema(idl).process()
     print json.dumps(schema, indent=2)
 
 
 if __name__ == '__main__':
   Main()