Repository navigation
proposal: missing_code_block_language_in_doc_comment #59420
Description
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.
Activity
bwilkerson commentedon Feb 29, 2024
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 commentedon Feb 29, 2024
Replace!
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 commentedon Feb 29, 2024
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 commentedon Feb 29, 2024
30 days. Seems long enough to migrate.
True. I think true of any deprecation.
No. It is not a breaking change to stop printing any given text from
dart doc.Add 'missing_code_block_language_in_doc_comment' lint.
Add info strings to code blocks. (#146085)
Add `none` language strings to code blocks. (#146154)
Add `missing_code_block_language_in_doc_comment` lint. (#145354)
Add `missing_code_block_language_in_doc_comment` lint to flutter/engi…
feat: missing_code_block_language_in_doc_comment
[various] Add `missing_code_block_language_in_doc_comment` lint to fl…