Enable comment_references lint (#50)

Change the markdown link style in a few places to work around a bug with
the analyzer where links that are split across lines are not recognized
correctly.

analysis_options.yaml

@@ -27,8 +27,7 @@ linter:
   - camel_case_types
   - cancel_subscriptions
   - cascade_invocations
-  # Enable once https://github.com/dart-lang/sdk/issues/31761 is fixed
-  #- comment_references
+  - comment_references
   - constant_identifier_names
   - control_flow_in_finally
   - directives_ordering

lib/src/highlighter.dart

@@ -48,12 +48,13 @@ class Highlighter {
   /// when [highlight] is called.
   ///
   /// [color] may either be a [String], a [bool], or `null`. If it's a string,
-  /// it indicates an [ANSI terminal color
-  /// escape](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) that should
+  /// it indicates an [ANSI terminal color escape][] that should
   /// be used to highlight the span's text (for example, `"\u001b[31m"` will
   /// color red). If it's `true`, it indicates that the text should be
   /// highlighted using the default color. If it's `false` or `null`, it
   /// indicates that the text shouldn't be highlighted.
+  ///
+  /// [ANSI terminal color escape]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
   factory Highlighter(SourceSpan span, {color}) {
     if (color == true) color = colors.red;
     if (color == false) color = null;

lib/src/span.dart

@@ -52,8 +52,7 @@ abstract class SourceSpan implements Comparable<SourceSpan> {
   /// Formats [message] in a human-friendly way associated with this span.
   ///
   /// [color] may either be a [String], a [bool], or `null`. If it's a string,
-  /// it indicates an [ANSI terminal color
-  /// escape](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) that should
+  /// it indicates an [ANSI terminal color escape][] that should
   /// be used to highlight the span's text (for example, `"\u001b[31m"` will
   /// color red). If it's `true`, it indicates that the text should be
   /// highlighted using the default color. If it's `false` or `null`, it
@@ -62,6 +61,8 @@ abstract class SourceSpan implements Comparable<SourceSpan> {
   /// This uses the full range of Unicode characters to highlight the source
   /// span if [glyph.ascii] is `false` (the default), but only uses ASCII
   /// characters if it's `true`.
+  ///
+  /// [ANSI terminal color escape]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
   String message(String message, {color});
 
   /// Prints the text associated with this span in a user-friendly way.
@@ -71,8 +72,7 @@ abstract class SourceSpan implements Comparable<SourceSpan> {
   /// isn't a [SourceSpanWithContext], returns an empty string.
   ///
   /// [color] may either be a [String], a [bool], or `null`. If it's a string,
-  /// it indicates an [ANSI terminal color
-  /// escape](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) that should
+  /// it indicates an [ANSI terminal color escape][] that should
   /// be used to highlight the span's text (for example, `"\u001b[31m"` will
   /// color red). If it's `true`, it indicates that the text should be
   /// highlighted using the default color. If it's `false` or `null`, it
@@ -81,6 +81,8 @@ abstract class SourceSpan implements Comparable<SourceSpan> {
   /// This uses the full range of Unicode characters to highlight the source
   /// span if [glyph.ascii] is `false` (the default), but only uses ASCII
   /// characters if it's `true`.
+  ///
+  /// [ANSI terminal color escape]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
   String highlight({color});
 }