Initial cut at generating the AnalysisServer.java interface. Currently this generates a commented o…

pkg/analysis_server/tool/spec/to_html.dart

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * Code for displaying the API as HTML.  This is used both for generating a
  * full description of the API as a web page, and for generating doc comments
  * in generated code.
  */
 library to.html;
 
 import 'dart:convert';
 import 'dart:io';
 
 import 'package:html5lib/dom.dart' as dom;
 
 import 'api.dart';
 import 'codegen_tools.dart';
 import 'from_html.dart';
 import 'html_tools.dart';
 
 /**
  * Embedded stylesheet
  */
-final String stylesheet =
-    '''
+final String stylesheet = '''
 h1 {
   text-align: center;
 }
 pre {
   margin: 0px;
 }
 div.box {
   border: 1px solid rgb(0, 0, 0);
   background-color: rgb(207, 226, 243);
   padding: 0.5em;
 }
 dt {
   margin-top: 1em;
   margin-bottom: 1em;
 }
-'''.trim(
-    );
+'''.trim();
 
 /**
  * Helper methods for creating HTML elements.
  */
 abstract class HtmlMixin {
   void element(String name, Map<dynamic, String> attributes, [void callback()]);
 
   void anchor(String id, void callback()) {
     element('a', {
       'name': id
@@ skipping 37 matching lines @@
  * Visitor that generates a compact representation of a type, such as:
  *
  * {
  *   "id": String
  *   "error": optional Error
  *   "result": {
  *     "version": String
  *   }
  * }
  */
-class TypeVisitor extends HierarchicalApiVisitor with HtmlMixin,
-    HtmlCodeGenerator {
+class TypeVisitor extends HierarchicalApiVisitor with HtmlMixin, HtmlCodeGenerator {
   /**
    * Set of fields which should be shown in boldface, or null if no field
    * should be shown in boldface.
    */
   final Set<String> fieldsToBold;
 
   /**
    * True if a short description should be generated.  In a short description,
    * objects are shown as simply "object", and enums are shown as "String".
    */
@@ skipping 80 matching lines @@
   }
 }
 
 /**
  * Visitor that records the mapping from HTML elements to various kinds of API
  * nodes.
  */
 class ApiMappings extends HierarchicalApiVisitor {
   ApiMappings(Api api) : super(api);
 
-  Map<dom.Element, Domain> domains = <dom.Element, Domain> {};
+  Map<dom.Element, Domain> domains = <dom.Element, Domain>{};
 
   @override
   void visitDomain(Domain domain) {
     domains[domain.html] = domain;
   }
 }
 
 /**
  * Visitor that generates HTML documentation of the API.
  */
-class ToHtmlVisitor extends HierarchicalApiVisitor with HtmlMixin, HtmlGenerator
-    {
+class ToHtmlVisitor extends HierarchicalApiVisitor with HtmlMixin, HtmlGenerator {
   /**
    * Set of types defined in the API.
    */
   Set<String> definedTypes = new Set<String>();
 
   /**
    * Mappings from HTML elements to API nodes.
    */
   ApiMappings apiMappings;
 
@@ skipping 65 matching lines @@
     }
   }
 
   @override
   void visitNotification(Notification notification) {
     dt('notification', () {
       write(notification.longEvent);
     });
     dd(() {
       box(() {
-        showType('notification', notification.notificationType,
-            notification.params);
+        showType('notification', notification.notificationType, notification.params);
       });
       translateHtml(notification.html);
       describePayload(notification.params, 'Parameters');
     });
   }
 
   /**
    * Copy the contents of the given HTML element, translating the special
    * elements that define the API appropriately.
    */
-  void translateHtml(dom.Element html) {
+  void translateHtml(dom.Element html, {bool squashParagraphs: false}) {
     for (dom.Node node in html.nodes) {
       if (node is dom.Element) {
+        if (squashParagraphs && node.localName == 'p') {
+          translateHtml(node, squashParagraphs: squashParagraphs);
+          break;

[Paul Berry, 2014/08/12 18:04:02]

Should be "continue;"

[jwren, 2014/08/12 18:23:08]

Done.

+        }
         switch (node.localName) {
           case 'api':
-            translateHtml(node);
+            translateHtml(node, squashParagraphs: squashParagraphs);
             break;
           case 'domain':
             visitDomain(apiMappings.domains[node]);
             break;
           case 'head':
             head(() {
-              translateHtml(node);
+              translateHtml(node, squashParagraphs: squashParagraphs);
               element('style', {}, () {
                 writeln(stylesheet);
               });
             });
             break;
           case 'refactorings':
             visitRefactorings(api.refactorings);
             break;
           case 'types':
             visitTypes(api.types);
             break;
           case 'version':
-            translateHtml(node);
+            translateHtml(node, squashParagraphs: squashParagraphs);
             break;
           default:
             if (!specialElements.contains(node.localName)) {
               element(node.localName, node.attributes, () {
-                translateHtml(node);
+                translateHtml(node, squashParagraphs: squashParagraphs);
               });
             }
         }
       } else if (node is dom.Text) {
         String text = node.text;
         write(text);
       }
     }
   }
 
@@ skipping 10 matching lines @@
     Set<String> fieldsToBold = new Set<String>();
     if (typeForBolding != null) {
       for (TypeObjectField field in typeForBolding.fields) {
         fieldsToBold.add(field.name);
       }
     }
     pre(() {
       if (shortDesc != null) {
         write('$shortDesc: ');
       }
-      TypeVisitor typeVisitor = new TypeVisitor(api, fieldsToBold: fieldsToBold
-          );
+      TypeVisitor typeVisitor = new TypeVisitor(api, fieldsToBold: fieldsToBold);
       addAll(typeVisitor.collectHtml(() {
         typeVisitor.visitTypeDecl(type);
       }));
     });
   }
 
   /**
    * Describe the payload of request, response, notification, refactoring
    * feedback, or refactoring options.
    *
    * If [force] is true, then a section is inserted even if the payload is
    * null.
    */
   void describePayload(TypeObject subType, String name, {bool force: false}) {
     if (force || subType != null) {
       h4(() {
         write(name);
       });
       if (subType == null) {
         p(() {
           write('none');
         });
       } else {
         visitTypeDecl(subType);
       }
     }
   }
 
+  void javadocParams(TypeObject typeObject) {
+    if (typeObject != null) {
+      for (TypeObjectField field in typeObject.fields) {
+        write('@param ${field.name} ');
+        translateHtml(field.html, squashParagraphs: true);
+        br();
+      }
+    }
+  }
+
   @override
   void visitRequest(Request request) {
     dt('request', () {
       write(request.longMethod);
     });
     dd(() {
       box(() {
         showType('request', request.requestType, request.params);
         br();
         showType('response', request.responseType, request.result);
@@ skipping 25 matching lines @@
   void visitTypeEnum(TypeEnum typeEnum) {
     dl(() {
       super.visitTypeEnum(typeEnum);
     });
   }
 
   @override
   void visitTypeEnumValue(TypeEnumValue typeEnumValue) {
     bool isDocumented = false;
     for (dom.Node node in typeEnumValue.html.nodes) {
-      if ((node is dom.Element && node.localName != 'code') || (node is dom.Text
-          && node.text.trim().isNotEmpty)) {
+      if ((node is dom.Element && node.localName != 'code') || (node is dom.Text && node.text.trim().isNotEmpty)) {
         isDocumented = true;
         break;
       }
     }
     dt('value', () {
       write(typeEnumValue.value);
     });
     if (isDocumented) {
       dd(() {
         translateHtml(typeEnumValue.html);
@@ skipping 58 matching lines @@
  */
 main() {
   ToHtmlVisitor visitor = new ToHtmlVisitor(readApi());
   dom.Document document = new dom.Document();
   for (dom.Node node in visitor.collectHtml(visitor.visitApi)) {
     document.append(node);
   }
   File outputFile = new File('../../doc/api.html');
   outputFile.writeAsStringSync(document.outerHtml);
 }