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

double <br> elements, and adjust CSS to make it look good. Fix up a couple of
IDL files to just use newlines rather than <br> elements.

R=mangini@chromium.org, asargent@chromium.org
NOTRY=true

Review URL: https://codereview.chromium.org/404203002

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

chrome/common/extensions/api/app_window.idl

@@ -99,28 +99,35 @@ namespace app.window {
 
   dictionary FrameOptions {
     // Frame type: <code>none</code> or <code>chrome</code> (defaults to
-    // <code>chrome</code>).<br>
+    // <code>chrome</code>).
+    //
     // For <code>none</code>, the <code>-webkit-app-region</code> CSS property
     // can be used to apply draggability to the app's window.
+    //
     // <code>-webkit-app-region: drag</code> can be used to mark regions
     // draggable. <code>no-drag</code> can be used to disable this style on
-    // nested elements.<br>
+    // nested elements.
     DOMString? type;
     // Allows the frame color to be set. Frame coloring is only available if the
-    // frame type is <code>chrome</code>.<br>
+    // frame type is <code>chrome</code>.
+    //
     // Frame coloring is new in Chrome 36.
     DOMString? color;
     // Allows the frame color of the window when active to be set. Frame
-    // coloring is only available if the frame type is <code>chrome</code>.<br>
+    // coloring is only available if the frame type is <code>chrome</code>.
+    //
     // Frame coloring is only available if the frame type is
-    // <code>chrome</code>.<br>
+    // <code>chrome</code>.
+    //
     // Frame coloring is new in Chrome 36.
     DOMString? activeColor;
     // Allows the frame color of the window when inactive to be set differently
     // to the active color. Frame
-    // coloring is only available if the frame type is <code>chrome</code>.<br>
+    // coloring is only available if the frame type is <code>chrome</code>.
+    //
     // <code>inactiveColor</code> must be used in conjunction with <code>
-    // color</code>.<br>
+    // color</code>.
+    //
     // Frame coloring is new in Chrome 36.
     DOMString? inactiveColor;
   };
@@ -213,7 +220,8 @@ namespace app.window {
     // <code>-webkit-app-region</code> CSS property can be used to apply
     // draggability to the app's window. <code>-webkit-app-region: drag</code>
     // can be used to mark regions draggable. <code>no-drag</code> can be used
-    // to disable this style on nested elements.<br>
+    // to disable this style on nested elements.
+    //
     // Use of <code>FrameOptions</code> is new in M36.
     (DOMString or FrameOptions)? frame;
 
@@ -247,9 +255,10 @@ namespace app.window {
     // If true, the window will stay above most other windows. If there are
     // multiple windows of this kind, the currently focused window will be in
     // the foreground. Requires the <code>"alwaysOnTopWindows"</code>
-    // permission. Defaults to false.<br>
+    // permission. Defaults to false.
+    //
     // Call <code>setAlwaysOnTop()</code> on the window to change this property
-    // after creation.<br>
+    // after creation.
     boolean? alwaysOnTop;
 
     // If true, the window will be focused when created. Defaults to true.
@@ -258,10 +267,13 @@ namespace app.window {
 
   // Called in the creating window (parent) before the load event is called in
   // the created window (child). The parent can set fields or functions on the
-  // child usable from onload. E.g. background.js:<br>
+  // child usable from onload. E.g. background.js:
+  //
   // <code>function(createdWindow) { createdWindow.contentWindow.foo =
   // function () { }; };</code>
-  // <br>window.js:<br>
+  //
+  // window.js:
+  //
   // <code>window.onload = function () { foo(); }</code>
   callback CreateWindowCallback =
       void ([instanceOf=AppWindow] object createdWindow);
@@ -270,11 +282,13 @@ namespace app.window {
     // Focus the window.
     static void focus();
 
-    // Fullscreens the window.<br>
+    // Fullscreens the window.
+    //
     // The user will be able to restore the window by pressing ESC. An
     // application can prevent the fullscreen state to be left when ESC is
     // pressed by requesting the <b>overrideEscFullscreen</b> permission and
-    // canceling the event by calling .preventDefault(), like this:<br>
+    // canceling the event by calling .preventDefault(), like this:
+    //
     // <code>window.onKeyDown = function(e) { if (e.keyCode == 27 /* ESC */) {
     // e.preventDefault(); } };</code>
     static void fullscreen();

chrome/common/extensions/api/identity.idl

@@ -77,7 +77,8 @@ namespace identity {
 
   interface Functions {
     // Retrieves a list of AccountInfo objects describing the accounts
-    // present on the profile.<br>
+    // present on the profile.
+    //
     // <code>getAccounts</code> is only supported on dev channel.
     static void getAccounts(GetAccountsCallback callback);
 

chrome/common/extensions/docs/server2/app.yaml

 application: chrome-apps-doc
-version: 3-33-0
+version: 3-34-0
 runtime: python27
 api_version: 1
 threadsafe: false

chrome/common/extensions/docs/server2/cron.yaml

@@ -2,4 +2,4 @@ cron:
 - description: Repopulates all cached data.
   url: /_cron
   schedule: every 5 minutes
-  target: 3-33-0
+  target: 3-34-0

chrome/common/extensions/docs/static/sass/_api.scss

@@ -17,17 +17,23 @@
     .description {
       margin-left: 20px;
     }
-    table.innerTable {
-      margin: 10px 0;
-      td, th {
-        padding: 5px 10px;
-        border: 1px solid #eee;
-      }
-      th {
-        background: none;
+    table {
+      .innerTable {
+        margin: 10px 0;
+        td, th {
+          padding: 5px 10px;
+          border: 1px solid #eee;
+        }
+        th {
+          background: none;
+        }
       }
       p {
-        margin: 0;
+        margin-top: 0.75em;
+        margin-bottom: 0.75em;
+      }
+      p:first-child {
+        margin-top: 0;
       }
     }
     td, th {

tools/json_schema_compiler/dart_test/comments.dart

@@ -18,12 +18,12 @@ class API_comments {
   /*
    * Functions
    */
-  /// There's a blank line at the start of this comment.  Documentation for
-  /// basicFunction. BasicFunction() is a great function. There is a newline
-  /// after this.<br/><br/> It works like so:        +-----+        |     |
-  /// +--+        |     |     |  |        +-----+ --> +--+<br/><br/> Some other
-  /// stuff here.    This paragraph starts with whitespace.    Overall, its a
-  /// great function. There's also a blank line at the end of this comment.
+  /// <p>There's a blank line at the start of this comment.</p><p>Documentation
+  /// for basicFunction. BasicFunction() is a great function. There is a newline
+  /// after this.</p><p>It works like so:        +-----+        |     |     +--+
+  ///       |     |     |  |        +-----+ --> +--+</p><p>Some other stuff here.
+  ///    This paragraph starts with whitespace.    Overall, its a great function.
+  /// There's also a blank line at the end of this comment.</p>
   void basicFunction() => JS('void', '#.basicFunction()', this._jsObject);
 
   API_comments(this._jsObject) {

tools/json_schema_compiler/dart_test/comments.idl

@@ -11,7 +11,7 @@ namespace comments {
   
     //
     // There's a blank line at the start of this comment.
-    // 
+    //
     // Documentation for basicFunction.
     // BasicFunction() is a great function.
     // There is a newline after this.

tools/json_schema_compiler/idl_schema.py

@@ -56,19 +56,20 @@ def ProcessComment(comment):
       }
     )
   '''
+  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,
@@ -79,9 +80,10 @@ def ProcessComment(comment):
     # 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)
 
 

tools/json_schema_compiler/idl_schema_test.py

@@ -226,9 +226,10 @@ class IdlSchemaTest(unittest.TestCase):
           '$ref': 'MyType1'}],
         func['parameters'])
     func = getFunction(schema, 'function4')
-    self.assertEquals(('This tests if "double-quotes" are escaped correctly.'
-                       '<br/><br/> It also tests a comment with two newlines.'),
-                      func['description'])
+    self.assertEquals(
+        '<p>This tests if "double-quotes" are escaped correctly.</p>'
+        '<p>It also tests a comment with two newlines.</p>',
+        func['description'])
 
   def testReservedWords(self):
     schema = idl_schema.Load('test/idl_reserved_words.idl')[0]