updates to the analysis server generated spec doc

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;
@@ skipping 18 matching lines @@
   margin: 0 auto;
   padding: 0 16px;
   font-size: 16px;
   line-height: 1.5;
   color: #111;
   background-color: #fdfdfd;
   font-weight: 300;
   -webkit-font-smoothing: auto;
 }
 
-h1 {
-  text-align: center;
-}
-
 h2, h3, h4, h5 {
   margin-bottom: 0;
 }
 
 h2.domain {
   border-bottom: 1px solid rgb(200, 200, 200);
   margin-bottom: 0.5em;
 }
 
 h4 {
@@ skipping 55 matching lines @@
 }
 
 a {
   text-decoration: none;
 }
 
 a:focus, a:hover {
   text-decoration: underline;
 }
 
+.deprecated {
+  text-decoration: line-through;
+}
+
 /* Styles for index */
 
 .subindex ul {
   padding-left: 0;
   margin-left: 0;
 
   -webkit-margin-before: 0;
   -webkit-margin-start: 0;
   -webkit-padding-start: 0;
 
@@ skipping 65 matching lines @@
 
   void h3(void callback()) => element('h3', {}, callback);
   void h4(void callback()) => element('h4', {}, callback);
   void h5(void callback()) => element('h5', {}, callback);
   void hangingIndent(void callback()) =>
       element('div', {'class': 'hangingIndent'}, callback);
   void head(void callback()) => element('head', {}, callback);
   void html(void callback()) => element('html', {}, callback);
   void i(void callback()) => element('i', {}, callback);
   void li(void callback()) => element('li', {}, callback);
-  void link(String id, void callback()) {
-    element('a', {'href': '#$id'}, callback);
+  void link(String id, void callback(), [Map<dynamic, String> attributes]) {
+    attributes ??= {};
+    attributes['href'] = '#$id';
+    element('a', attributes, callback);
   }
 
   void p(void callback()) => element('p', {}, callback);
   void pre(void callback()) => element('pre', {}, callback);
   void title(void callback()) => element('title', {}, callback);
   void tt(void callback()) => element('tt', {}, callback);
   void ul(void callback()) => element('ul', {}, callback);
+  void span(String cls, void callback()) =>
+      element('span', {'class': cls}, callback);
 }
 
 /**
  * Visitor that generates HTML documentation of the API.
  */
 class ToHtmlVisitor extends HierarchicalApiVisitor
     with HtmlMixin, HtmlGenerator {
   /**
    * Set of types defined in the API.
    */
@@ skipping 111 matching lines @@
           element(
               'li',
               {},
               () => link('request_${request.longMethod}',
                   () => write(request.method)));
         }
       }
     });
   }
 
+  void generateDomainsHeader() {
+    h1(() {
+      write('Domains');
+    });
+  }
+
   void generateTableOfContents() {
-    ul(() {
+    for (var domain in api.domains.where((domain) => !domain.experimental)) {
       writeln();
 
-      for (var domain in api.domains.where((domain) => !domain.experimental)) {
-        write('      ');
-        li(() {
-          link('domain_${domain.name}', () {
-            write(_toTitleCase(domain.name));
+      p(() {
+        link('domain_${domain.name}', () {
+          write(_toTitleCase(domain.name));
+        });
+      });
+
+      ul(() {
+        for (Request request in domain.requests) {
+          li(() {
+            link('request_${request.longMethod}', () {
+              write(request.longMethod);
+            }, request.deprecated ? {'class': 'deprecated'} : null);
           });
-        });
-        writeln();
-      }
-    });
+          writeln();
+        }
+      });
+
+      writeln();
+    }
   }
 
   void generateTypesIndex(Set<String> types) {
     h3(() {
       write("Types");
       write(' (');
       link('types', () => write('\u2191'));
       write(')');
     });
     element('div', {'class': 'subindex'}, () {
@@ skipping 49 matching lines @@
    * elements that define the API appropriately.
    */
   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);
           continue;
         }
         switch (node.localName) {
+          case 'domains':
+            generateDomainsHeader();
+            break;
           case 'domain':
             visitDomain(apiMappings.domains[node]);
             break;
           case 'head':
             head(() {
               translateHtml(node, squashParagraphs: squashParagraphs);
               element('link', {
                 'rel': 'stylesheet',
                 'href':
                     'https://fonts.googleapis.com/css?family=Source+Code+Pro|Roboto:500,400italic,300,400',
@@ skipping 72 matching lines @@
       });
     }
   }
 
   @override
   void visitNotification(Notification notification) {
     dt('notification', () {
       anchor('notification_${notification.longEvent}', () {
         write(notification.longEvent);
       });
-      write(' (');
-      link('notification_${notification.longEvent}', () {
-        write('#');
-      });
-      write(')');
     });
     dd(() {
       box(() {
         showType(
             'notification', notification.notificationType, notification.params);
       });
       translateHtml(notification.html);
       describePayload(notification.params, 'parameters:');
     });
   }
@@ skipping 16 matching lines @@
     dl(() {
       super.visitRefactorings(refactorings);
     });
   }
 
   @override
   void visitRequest(Request request) {
     if (request.experimental) {
       return;
     }
-    dt('request', () {
+    dt(request.deprecated ? 'request deprecated' : 'request', () {
       anchor('request_${request.longMethod}', () {
         write(request.longMethod);
       });
-      write(' (');
-      link('request_${request.longMethod}', () {
-        write('#');
-      });
-      write(')');
     });
     dd(() {
       box(() {
         showType('request', request.requestType, request.params);
         br();
         showType('response', request.responseType, request.result);
       });
       translateHtml(request.html);
       describePayload(request.params, 'parameters:');
       describePayload(request.result, 'returns:');
     });
   }
 
   @override
   void visitTypeDefinition(TypeDefinition typeDefinition) {
     if (typeDefinition.experimental) {
       return;
     }
-    dt('typeDefinition', () {
+    dt(
+        typeDefinition.deprecated
+            ? 'typeDefinition deprecated'
+            : 'typeDefinition', () {
       anchor('type_${typeDefinition.name}', () {
         write('${typeDefinition.name}: ');
         TypeVisitor typeVisitor = new TypeVisitor(api, short: true);
         addAll(typeVisitor.collectHtml(() {
           typeVisitor.visitTypeDecl(typeDefinition.type);
         }));
       });
     });
     dd(() {
       translateHtml(typeDefinition.html);
@@ skipping 11 matching lines @@
   @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)) {
         isDocumented = true;
         break;
       }
     }
-    dt('value', () {
+    dt(typeEnumValue.deprecated ? 'value deprecated' : 'value', () {
       write(typeEnumValue.value);
     });
     if (isDocumented) {
       dd(() {
         translateHtml(typeEnumValue.html);
       });
     }
   }
 
   @override
@@ skipping 10 matching lines @@
   void visitTypeObject(TypeObject typeObject) {
     dl(() {
       super.visitTypeObject(typeObject);
     });
   }
 
   @override
   void visitTypeObjectField(TypeObjectField typeObjectField) {
     dt('field', () {
       b(() {
-        write(typeObjectField.name);
+        if (typeObjectField.deprecated) {
+          span('deprecated', () {
+            write(typeObjectField.name);
+          });
+        } else {
+          write(typeObjectField.name);
+        }
         if (typeObjectField.value != null) {
           write(' = ${JSON.encode(typeObjectField.value)}');
         } else {
-          write(' (');
-          if (typeObjectField.optional) {
-            gray(() {
-              write('optional');
-            });
-            write(' ');
-          }
+          write(': ');
           TypeVisitor typeVisitor = new TypeVisitor(api, short: true);
           addAll(typeVisitor.collectHtml(() {
             typeVisitor.visitTypeDecl(typeObjectField.type);
           }));
-          write(')');
+          if (typeObjectField.optional) {
+            gray(() => write(' (optional)'));
+          }
         }
       });
     });
     dd(() {
       translateHtml(typeObjectField.html);
     });
   }
 
   @override
   void visitTypeReference(TypeReference typeReference) {}
@@ skipping 117 matching lines @@
     bool verticalBarNeeded = false;
     for (TypeDecl choice in typeUnion.choices) {
       if (verticalBarNeeded) {
         write(' | ');
       }
       visitTypeDecl(choice);
       verticalBarNeeded = true;
     }
   }
 }