proposal: missing_code_block_language_in_doc_comment

[kallentu]

missing_code_block_language_in_doc_comment

Description

A fenced code block is missing a specified language.

Details

To enable proper syntax highlighting of Markdown code blocks, dart doc requires code blocks to specify the language used after the initial declaration.

Kind

It guards against syntax highlighting errors.

DO specify the language used in the code block of a doc comment.

Bad Examples

/// ```
/// void main() {}
/// ```

/// ~~~
/// void main() {}
/// ~~~

Good Examples

/// ```dart
/// void main() {}
/// ```

/// ~~~dart
/// void main() {}
/// ~~~

Discussion

This migrates Dartdoc's missingCodeBlockLanguage warning to the linter for the clean up of Dartdoc.

cc. @srawlins @goderbauer @pq

Discussion checklist

• List any existing rules this proposal modifies, complements, overlaps or conflicts with.
• List any relevant issues (reported here, the SDK Tracker, or elsewhere).
• If there's any prior art (e.g., in other linters), please add references here.
• If this proposal corresponds to Effective Dart or Flutter Style Guide advice, please call it out. (If there isn't any corresponding advice, should there be?)
• If this proposal is motivated by real-world examples, please provide as many details as you can. Demonstrating potential impact is especially valuable.

[bwilkerson]

The design of the lint looks fine, but I have a couple of related questions.

Would this replace the warning in dartdoc, or would it duplicate it?

Are there any plans for how to advertise the new lint to users of the current warning?

[srawlins]

Would this replace the warning in dartdoc, or would it duplicate it?

Replace!

Are there any plans for how to advertise the new lint to users of the current warning?

I think to enable the warning, you have to specify it in the dartdoc options file; flutter has a line, commented out. So when we deprecate the dartdoc functionality, we can refer folks to the lint rule.

[bwilkerson]

I like those answers, but they raised more. (Let me know if we should move this discussion elsewhere.)

How long after deprecating the warning in dartdoc will the warning need to continue to be supported? It used to be the case that many users ran dartdoc from the package (via pub global activate), not from the SDK. If users who are doing that upgrade dartdoc to a version that doesn't report the warning without upgrading their SDK to a version where analyzer can report the lint, they could be left without any warnings.

Will we need a breaking change announcement to let users know that they now need to run the analyzer in order to catch this issue? (I like to imagine that every user runs the analyzer, but I don't know that we can depend on that.)

[srawlins]

How long after deprecating the warning in dartdoc will the warning need to continue to be supported?

30 days. Seems long enough to migrate.

If users who are doing that upgrade dartdoc to a version that doesn't report the warning without upgrading their SDK to a version where analyzer can report the lint, they could be left without any warnings.

True. I think true of any deprecation.

Will we need a breaking change announcement to let users know that they now need to run the analyzer in order to catch this issue? (I like to imagine that every user runs the analyzer, but I don't know that we can depend on that.)

No. It is not a breaking change to stop printing any given text from dart doc.