Repository navigation
Standardize and robustify dartdoc directive parsing logic #4205
Description
Currently, dartdoc directives are processed using a series of independent regular expressions on the raw documentation string. This "regex soup" approach lacks context awareness and leads to several robustness issues.
This issue tracks the work to unify the parsing logic and implement a standard set of rules for all directives. We should consider the following:
-
Context Awareness (Code Fences):
Directives could be ignored if they appear inside Markdown code blocks (fenced ``` or inline `). -
Escaping Support:
Implement a standard escaping mechanism (e.g.,\{@directive ...}) to allow users to document directives literally without executing them. -
Line-Level Enforcement (for Block Directives):
Block-level directives could be required to appear on their own line . -
Strict Argument Parsing:
The current shared_parseArgsutility (backed bypackage:args) accidentally allows flag-style arguments (e.g.,--lang=dart) in addition to the documentedkey=valuesyntax. Decide on the canonical syntax (likelykey=value) and update the parser to strictly enforce it. -
Move Parsing to Analyzer:
Ideally, the parsing, resolution, and validation logic for these directives should live in theanalyzerpackage. This would enable IDE features like hover previews, auto-completion, and real-time error reporting for directives.
Activity
jonasfj commentedon Feb 13, 2026
I'd add the following considerations aswell:
(A) Should dartdoc directives always be on the form
{@<directive> <args...> [<option>=...]}.Today, most are on this form, except
@nodoc. We could allow{@nodoc}and deprecate the old@nodoc.(B) What casing should dartdoc directives have.
camelCase, like{@subCategory}and{@canonicalFor}.kebab-stick, like{@inject-html},{@end-inject-html},{@end-tool}.monocase, like@nodocand{@endtemplate}.(C) How should block-style dartdoc directives be terminated.
{@end-inject-html}and{@endtemplate}{/inject-html}and{/template}?(D) How should arguments and options be passed to dartdoc directives?
{@category Assets and Icons}{@subCategory Information displays}{@template template_name}{@macro template_name}{@youtube 320 240 https://www.youtube.com/watch?v=oHg5SJYRHA0}{@animation 320 240 URL [id=ID]}{@canonicalFor some_library.SomeClass}{@example path/to/file.dart [lang=dart] [indent=strip]}{@tool drill --flag --option="value" $INPUT}We might have to choose our battles here. Some of these are easy to do.
But it would be nice if dartdoc directive parsing wasn't specific to the kind of directive being parsed.
srawlins commentedon Feb 13, 2026
There is currently parsing, resolution, and validation in the analyzer for most (all?) of the existing directives. Dartdoc just doesn't use it yet. The parsed results live in the Comment class which has
.docDirectives, a list of DocDirectives. This data can live in the ModelNode class, as it is not stored in the analyzer element model, and so needs to be snatched from the AST.This can be stored in ModelNodes. See how CommentData there already has
CommentDocImportData.