Fix doc comment bugs, enable the corresponding lint

pkgs/markdown/analysis_options.yaml

@@ -11,13 +11,9 @@ analyzer:
     # The example app explicitly takes a String of user-generated HTML and
     # inserts it straight into a <div> using innerHtml.
     unsafe_html: ignore
-    # Waiting on a couple of bug fixes and new features before this should be enabled
-    comment_references: ignore
 
 linter:
   rules:
-    # https://github.com/dart-lang/linter/issues/574
-    #- comment_references
     - avoid_private_typedef_functions
     - avoid_redundant_argument_values
     - avoid_unused_constructor_parameters

pkgs/markdown/lib/markdown.dart

@@ -36,6 +36,12 @@
 ///   - Creating a new [ExtensionSet] from one of the existing flavors
 ///     and adding your syntaxes.
 ///   - Passing your syntaxes to [Document] or [markdownToHtml] as parameters.
+/// @docImport 'src/ast.dart';
+/// @docImport 'src/block_syntaxes/block_syntax.dart';
+/// @docImport 'src/document.dart';
+/// @docImport 'src/extension_set.dart';
+/// @docImport 'src/html_renderer.dart';
+/// @docImport 'src/inline_syntaxes/inline_syntax.dart';
 library;
 
 import 'src/version.dart';

pkgs/markdown/lib/src/block_parser.dart

@@ -2,6 +2,9 @@
 // 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.
 
+/// @docImport 'block_syntaxes/setext_header_syntax.dart';
+library;
+
 import 'ast.dart';
 import 'block_syntaxes/block_syntax.dart';
 import 'block_syntaxes/blockquote_syntax.dart';
@@ -53,6 +56,10 @@ class BlockParser {
   bool encounteredBlankLine = false;
 
   /// The collection of built-in block parsers.
+  // TODO(kevmoo): this should be static const and private!
+  // The fact that it's mutable is a BUG!
+  @Deprecated('Implementation member. '
+      'Will be removed or make static in the next release.')
   final List<BlockSyntax> standardBlockSyntaxes = [
     const EmptyBlockSyntax(),
     const HtmlBlockSyntax(),
@@ -135,7 +142,7 @@ class BlockParser {
   BlockSyntax? get parentSyntax => _parentSyntax;
   BlockSyntax? _parentSyntax;
 
-  /// Whether the [SetextHeadingSyntax] is disabled temporarily.
+  /// Whether the [SetextHeaderSyntax] is disabled temporarily.
   bool get setextHeadingDisabled => _setextHeadingDisabled;
   bool _setextHeadingDisabled = false;
 

pkgs/markdown/lib/src/inline_syntaxes/footnote_ref_syntax.dart

@@ -1,3 +1,6 @@
+/// @docImport 'link_syntax.dart';
+library;
+
 import '../ast.dart' show Element, Node, Text;
 import '../charcode.dart';
 import 'link_syntax.dart' show LinkContext;

pkgs/markdown/lib/src/inline_syntaxes/link_syntax.dart

@@ -11,7 +11,9 @@ import 'delimiter_syntax.dart';
 import 'footnote_ref_syntax.dart';
 
 /// A helper class holds params of link context.
-/// Footnote creation needs other info in [_tryCreateReferenceLink].
+// Footnote creation needs other info in [LinkSyntax._tryCreateReferenceLink].
+// TODO(kevmoo): this type should be private. Ideally a Record.
+@Deprecated('Implementation class that should not be used directly.')
 class LinkContext {
   final InlineParser parser;
   final SimpleDelimiter opener;
@@ -202,8 +204,8 @@ class LinkSyntax extends DelimiterSyntax {
 
   /// Parse a reference link label at the current position.
   ///
-  /// Specifically, [parser.pos] is expected to be pointing at the `[` which
-  /// opens the link label.
+  /// Specifically, [InlineParser.pos] is expected to be pointing at the
+  /// `[` which opens the link label.
   ///
   /// Returns the label if it could be parsed, or `null` if not.
   String? _parseReferenceLinkLabel(InlineParser parser) {
@@ -245,7 +247,8 @@ class LinkSyntax extends DelimiterSyntax {
   /// Parse an inline [InlineLink] at the current position.
   ///
   /// At this point, we have parsed a link's (or image's) opening `[`, and then
-  /// a matching closing `]`, and [parser.pos] is pointing at an opening `(`.
+  /// a matching closing `]`, and [InlineParser.pos] is pointing at an opening
+  /// `(`.
   /// This method will then attempt to parse a link destination wrapped in `<>`,
   /// such as `(<http://url>)`, or a bare link destination, such as
   /// `(http://url)`, or a link destination with a title, such as