Generate end-of-line doc comments in server and plugin packages

Change-Id: I1d5517932e1c78744cfe43fc6a768a104e527091
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/129520
Reviewed-by: Phil Quitslund <pquitslund@google.com>
Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>

Author: bwilkerson

pkg/analysis_server/lib/protocol/protocol_generated.dart

@@ -20,16 +20,47 @@ GeneratedFile clientTarget() {
   });
 }
 
+_capitalize(String name) =>
+    '${name.substring(0, 1).toUpperCase()}${name.substring(1)}';
+
+List<String> _generateDartDoc(Element html) => html.children
+    .where((Element elem) => elem.localName == 'p')
+    .map<String>((Element elem) => elem.text.trim())
+    .toList();
+
+String _generateNotificationMethodName(String domainName, String event) =>
+    'on${_capitalize(domainName)}${_capitalize(event)}';
+
+String _generateParamTypeName(String domainName, String event) =>
+    '${_capitalize(domainName)}${_capitalize(event)}Params';
+
 /**
  * Visitor which produces Dart code representing the API.
  */
 class CodegenNotificationHandlerVisitor extends DartCodegenVisitor
     with CodeGenerator {
   CodegenNotificationHandlerVisitor(Api api) : super(api) {
     codeGeneratorSettings.commentLineLength = 79;
+    codeGeneratorSettings.docCommentStartMarker = null;
+    codeGeneratorSettings.docCommentLineLeader = '/// ';
+    codeGeneratorSettings.docCommentEndMarker = null;
     codeGeneratorSettings.languageName = 'dart';
   }
 
+  void emitDartdoc(List<String> dartdoc) {
+    bool first = true;
+    for (String paragraph in dartdoc) {
+      if (first) {
+        first = false;
+      } else {
+        writeln('  ///');
+      }
+      for (String line in paragraph.split(RegExp('\r?\n'))) {
+        writeln('  /// ${line.trim()}');
+      }
+    }
+  }
+
   void emitImports() {
     writeln("import 'package:analysis_server_client/protocol.dart';");
   }
@@ -78,20 +109,6 @@ mixin NotificationHandler {
     writeln('}');
   }
 
-  void emitDartdoc(List<String> dartdoc) {
-    bool first = true;
-    for (String paragraph in dartdoc) {
-      if (first) {
-        first = false;
-      } else {
-        writeln('  ///');
-      }
-      for (String line in paragraph.split(RegExp('\r?\n'))) {
-        writeln('  /// ${line.trim()}');
-      }
-    }
-  }
-
   @override
   visitApi() {
     outputHeader(year: '2018');
@@ -127,17 +144,3 @@ class _NotificationVisitor extends HierarchicalApiVisitor {
         _generateDartDoc(notification.html)));
   }
 }
-
-List<String> _generateDartDoc(Element html) => html.children
-    .where((Element elem) => elem.localName == 'p')
-    .map<String>((Element elem) => elem.text.trim())
-    .toList();
-
-String _generateNotificationMethodName(String domainName, String event) =>
-    'on${_capitalize(domainName)}${_capitalize(event)}';
-
-String _generateParamTypeName(String domainName, String event) =>
-    '${_capitalize(domainName)}${_capitalize(event)}Params';
-
-_capitalize(String name) =>
-    '${name.substring(0, 1).toUpperCase()}${name.substring(1)}';

pkg/analysis_server/test/integration/support/integration_test_methods.dart

@@ -119,6 +119,9 @@ class CodegenProtocolVisitor extends DartCodegenVisitor with CodeGenerator {
         impliedTypes = computeImpliedTypes(api),
         super(api) {
     codeGeneratorSettings.commentLineLength = 79;
+    codeGeneratorSettings.docCommentStartMarker = null;
+    codeGeneratorSettings.docCommentLineLeader = '/// ';
+    codeGeneratorSettings.docCommentEndMarker = null;
     codeGeneratorSettings.languageName = 'dart';
   }
 
@@ -324,9 +327,7 @@ class CodegenProtocolVisitor extends DartCodegenVisitor with CodeGenerator {
         writeln();
       }
 
-      writeln('/**');
-      writeln(' * A list containing all of the enum values that are defined.');
-      writeln(' */');
+      writeln('/// A list containing all of the enum values that are defined.');
       write('static const List<');
       write(className);
       write('> VALUES = <');

pkg/analysis_server/test/integration/support/protocol_matchers.dart

@@ -53,6 +53,9 @@ class CodegenInttestMethodsVisitor extends DartCodegenVisitor
       : toHtmlVisitor = ToHtmlVisitor(api),
         super(api) {
     codeGeneratorSettings.commentLineLength = 79;
+    codeGeneratorSettings.docCommentStartMarker = null;
+    codeGeneratorSettings.docCommentLineLeader = '/// ';
+    codeGeneratorSettings.docCommentEndMarker = null;
     codeGeneratorSettings.languageName = 'dart';
   }
 
@@ -99,9 +102,7 @@ class CodegenInttestMethodsVisitor extends DartCodegenVisitor
   visitApi() {
     outputHeader(year: '2017');
     writeln();
-    writeln('/**');
-    writeln(' * Convenience methods for running integration tests');
-    writeln(' */');
+    writeln('/// Convenience methods for running integration tests.');
     writeln("import 'dart:async';");
     writeln();
     writeln("import 'package:$packageName/protocol/protocol_generated.dart';");
@@ -117,9 +118,7 @@ class CodegenInttestMethodsVisitor extends DartCodegenVisitor
       writeln("';");
     }
     writeln();
-    writeln('/**');
-    writeln(' * Convenience methods for running integration tests');
-    writeln(' */');
+    writeln('/// Convenience methods for running integration tests.');
     writeln('abstract class IntegrationTestMixin {');
     indent(() {
       writeln('Server get server;');

pkg/analysis_server/tool/spec/codegen_dart_notification_handler.dart

@@ -36,6 +36,9 @@ class CodegenMatchersVisitor extends HierarchicalApiVisitor with CodeGenerator {
       : toHtmlVisitor = ToHtmlVisitor(api),
         super(api) {
     codeGeneratorSettings.commentLineLength = 79;
+    codeGeneratorSettings.docCommentStartMarker = null;
+    codeGeneratorSettings.docCommentLineLeader = '/// ';
+    codeGeneratorSettings.docCommentEndMarker = null;
     codeGeneratorSettings.languageName = 'dart';
   }
 
@@ -98,9 +101,7 @@ class CodegenMatchersVisitor extends HierarchicalApiVisitor with CodeGenerator {
   visitApi() {
     outputHeader(year: '2017');
     writeln();
-    writeln('/**');
-    writeln(' * Matchers for data types defined in the analysis server API');
-    writeln(' */');
+    writeln('/// Matchers for data types defined in the analysis server API.');
     writeln("import 'package:test/test.dart';");
     writeln();
     writeln("import 'integration_tests.dart';");

pkg/analysis_server/tool/spec/codegen_dart_protocol.dart

@@ -32,12 +32,40 @@ String generateConstName(String domainName, String kind, String name) {
   return _fromComponents(components);
 }
 
+/**
+   * Return a name generated by converting each of the given [components] to an
+   * uppercase equivalent, then joining them with underscores.
+   */
+String _fromComponents(List<String> components) =>
+    components.map((String component) => component.toUpperCase()).join('_');
+
+/**
+   * Return the components of the given [string] that are indicated by an upper
+   * case letter.
+   */
+Iterable<String> _split(String first) {
+  RegExp regExp = RegExp('[A-Z]');
+  List<String> components = <String>[];
+  int start = 1;
+  int index = first.indexOf(regExp, start);
+  while (index >= 0) {
+    components.add(first.substring(start - 1, index));
+    start = index + 1;
+    index = first.indexOf(regExp, start);
+  }
+  components.add(first.substring(start - 1));
+  return components;
+}
+
 /**
  * A visitor that produces Dart code defining constants associated with the API.
  */
 class CodegenVisitor extends DartCodegenVisitor with CodeGenerator {
   CodegenVisitor(Api api) : super(api) {
     codeGeneratorSettings.commentLineLength = 79;
+    codeGeneratorSettings.docCommentStartMarker = null;
+    codeGeneratorSettings.docCommentLineLeader = '/// ';
+    codeGeneratorSettings.docCommentEndMarker = null;
     codeGeneratorSettings.languageName = 'dart';
   }
 
@@ -153,28 +181,3 @@ class _ConstantVisitor extends HierarchicalApiVisitor {
     });
   }
 }
-
-/**
-   * Return a name generated by converting each of the given [components] to an
-   * uppercase equivalent, then joining them with underscores.
-   */
-String _fromComponents(List<String> components) =>
-    components.map((String component) => component.toUpperCase()).join('_');
-
-/**
-   * Return the components of the given [string] that are indicated by an upper
-   * case letter.
-   */
-Iterable<String> _split(String first) {
-  RegExp regExp = RegExp('[A-Z]');
-  List<String> components = <String>[];
-  int start = 1;
-  int index = first.indexOf(regExp, start);
-  while (index >= 0) {
-    components.add(first.substring(start - 1, index));
-    start = index + 1;
-    index = first.indexOf(regExp, start);
-  }
-  components.add(first.substring(start - 1));
-  return components;
-}