Linter: comment_references should ignore escaped opening `[`

[kevmoo]

\[ is an escaped opening bracket in markdown.

The linter should not consider such a bracket for the purpose of finding comment references.

[pq]

Can you give an example where we're flagging this wrong?

[kevmoo]

/// Examples: counter { metric: "/debug_access_count" field: "iam_principal" }
/// ==> increment counter /iam/policy/debug_access_count {iam_principal=\[value
/// of IAMContext.principal\]}

This is auto-generated for the googleapis package

I want to be able to put in (escaped) [ characters

[pq]

Thanks!

[srawlins]

We might want to fix this with a big hammer, because I think there are many avoidable false positives in comment_references.

For a long time I've wanted to add an AST structure in the markdown package using SourceSpans. With this tooling, you could take a dartdoc comment like:

/// [ref] and \[non-ref\]
/// and `code with [not a ref]`.

and get back an AST like [ReferenceLink(label="ref"), TextNode(" \[non-ref\]\nand "), Code("code with [not a ref]")]

You can then check all ReferenceLinks. When one is an unknown reference, you can look at ReferenceLink.span.line, etc. and report there.

[kevmoo]

I would LOVE that @srawlins