Handle references to other classes in comments

Change-Id: I0a29355e0bbcb2a441dff90bc2cfc3475e8c1cd3
Reviewed-on: https://dart-review.googlesource.com/c/79321
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Danny Tuppeny <dantup@google.com>

pkg/analysis_server/lib/lsp_protocol/protocol_generated.dart

@@ -189,7 +189,7 @@ class ColorInformation {
 }
 
 class ColorPresentation {
-  /// An optional array of additional [text edits](#TextEdit) that are applied
+  /// An optional array of additional text edits ([TextEdit]) that are applied
   /// when selecting this color presentation. Edits must not overlap with the
   /// main [edit](#ColorPresentation.textEdit) nor with themselves.
   List<TextEdit> additionalTextEdits;
@@ -199,7 +199,7 @@ class ColorPresentation {
   /// this color presentation.
   String label;
 
-  /// An [edit](#TextEdit) which is applied to a document when selecting this
+  /// An edit ([TextEdit]) which is applied to a document when selecting this
   /// presentation for the color.  When `falsy` the
   /// [label](#ColorPresentation.label) is used.
   TextEdit textEdit;
@@ -374,7 +374,7 @@ abstract class CompletionItemKind {
   static const Variable = 6;
 }
 
-/// Represents a collection of [completion items](#CompletionItem) to be
+/// Represents a collection of completion items ([CompletionItem]) to be
 /// presented in the editor.
 class CompletionList {
   /// This list it not complete. Further typing should result in recomputing
@@ -804,8 +804,8 @@ class FoldingRange {
 
   /// Describes the kind of the folding range such as `comment' or 'region'. The
   /// kind is used to categorize folding ranges and used by commands like 'Fold
-  /// all comments'. See [FoldingRangeKind](#FoldingRangeKind) for an
-  /// enumeration of standardized kinds.
+  /// all comments'. See [FoldingRangeKind] for an enumeration of standardized
+  /// kinds.
   String kind;
 
   /// The zero-based character offset from where the folded range starts. If not
@@ -1087,8 +1087,7 @@ class RenameOptions {
 
 class RenameParams {
   /// The new name of the symbol. If the given name is not valid the request
-  /// must return a [ResponseError](#ResponseError) with an appropriate message
-  /// set.
+  /// must return a [ResponseError] with an appropriate message set.
   String newName;
 
   /// The position at which this request was sent.

pkg/analysis_server/test/tool/lsp_spec/typescript_to_dart_test.dart

@@ -53,5 +53,25 @@ class SomeDocumentThing {
     ''';
       convertAndCompare(input, expectedOutput);
     });
+
+    test('outputs references in comments in the correct format', () {
+      final String input = '''
+export interface One {
+}
+
+/**
+ *  This may refer to [a one](#One) or just [One](#One).
+ */
+export interface Two {
+}
+    ''';
+      final String expectedOutput = '''
+class One {}
+
+/// This may refer to a one ([One]) or just [One].
+class Two {}
+    ''';
+      convertAndCompare(input, expectedOutput);
+    });
   });
 }

pkg/analysis_server/tool/lsp_spec/codegen_dart.dart

@@ -36,6 +36,19 @@ String _mapType(String type) {
   return types[type] ?? type;
 }
 
+String _rewriteCommentReference(String comment) {
+  final commentReferencePattern = new RegExp(r'\[([\w ]+)\]\(#(\w+)\)');
+  return comment.replaceAllMapped(commentReferencePattern, (m) {
+    final description = m.group(1);
+    final reference = m.group(2);
+    if (description == reference) {
+      return '[$reference]';
+    } else {
+      return '$description ([$reference])';
+    }
+  });
+}
+
 Iterable<String> _wrapLines(List<String> lines, int maxLength) sync* {
   lines = lines.map((l) => l.trimRight()).toList();
   for (var line in lines) {
@@ -68,6 +81,7 @@ void _writeDocComment(IndentableStringBuffer buffer, String comment) {
   if (comment == null || comment.length == 0) {
     return;
   }
+  comment = _rewriteCommentReference(comment);
   Iterable<String> lines = comment.split('\n');
   // Wrap at 80 - 4 ('/// ') - indent characters.
   lines = _wrapLines(lines, 80 - 4 - buffer.totalIndent);