From 18a07a0d06575b53a69467b738ed05260112329f Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Thu, 13 Nov 2025 18:14:32 -0800 Subject: [PATCH 1/2] Fix doc comment bugs, enable the corresponding lint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Now that the underlying bug is fixed Also flagged a couple of TODOs – but requires a breaking change to be careful --- pkgs/markdown/analysis_options.yaml | 4 ---- pkgs/markdown/lib/markdown.dart | 6 ++++++ pkgs/markdown/lib/src/block_parser.dart | 9 ++++++++- .../lib/src/inline_syntaxes/footnote_ref_syntax.dart | 3 +++ .../markdown/lib/src/inline_syntaxes/link_syntax.dart | 11 +++++++---- 5 files changed, 24 insertions(+), 9 deletions(-) diff --git a/pkgs/markdown/analysis_options.yaml b/pkgs/markdown/analysis_options.yaml index e7748f55a..76bf2549e 100644 --- a/pkgs/markdown/analysis_options.yaml +++ b/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
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 diff --git a/pkgs/markdown/lib/markdown.dart b/pkgs/markdown/lib/markdown.dart index 9fac7321d..5cd7468ca 100644 --- a/pkgs/markdown/lib/markdown.dart +++ b/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'; diff --git a/pkgs/markdown/lib/src/block_parser.dart b/pkgs/markdown/lib/src/block_parser.dart index efe2352c3..9148f5371 100644 --- a/pkgs/markdown/lib/src/block_parser.dart +++ b/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 make static in the next release.') final List 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; diff --git a/pkgs/markdown/lib/src/inline_syntaxes/footnote_ref_syntax.dart b/pkgs/markdown/lib/src/inline_syntaxes/footnote_ref_syntax.dart index 155fd74c4..c5d4ef6d6 100644 --- a/pkgs/markdown/lib/src/inline_syntaxes/footnote_ref_syntax.dart +++ b/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; diff --git a/pkgs/markdown/lib/src/inline_syntaxes/link_syntax.dart b/pkgs/markdown/lib/src/inline_syntaxes/link_syntax.dart index bca3efbe0..9ceaf94d3 100644 --- a/pkgs/markdown/lib/src/inline_syntaxes/link_syntax.dart +++ b/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 `()`, or a bare link destination, such as /// `(http://url)`, or a link destination with a title, such as From 8372c9713628309592168813d8d7c46f2a3b18d8 Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Thu, 13 Nov 2025 18:20:02 -0800 Subject: [PATCH 2/2] small typo. thanks gemini --- pkgs/markdown/lib/src/block_parser.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkgs/markdown/lib/src/block_parser.dart b/pkgs/markdown/lib/src/block_parser.dart index 9148f5371..28d4b2797 100644 --- a/pkgs/markdown/lib/src/block_parser.dart +++ b/pkgs/markdown/lib/src/block_parser.dart @@ -59,7 +59,7 @@ class BlockParser { // TODO(kevmoo): this should be static const and private! // The fact that it's mutable is a BUG! @Deprecated('Implementation member. ' - 'Will be removed make static in the next release.') + 'Will be removed or make static in the next release.') final List standardBlockSyntaxes = [ const EmptyBlockSyntax(), const HtmlBlockSyntax(),