-
Notifications
You must be signed in to change notification settings - Fork 695
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document todo rule #5401
Comments
Are there any other rules that might be missing from the reference documentation? |
Hi @tillulen |
Hi @huycozy, Thank you for the quick response!
No, that is a different rule. The The name of the undocumented rule seems to be just Here is the relevant section of the Customizing static analysis page where the
Here are two Stack Overflow questions about turning the rule on or off: |
Thanks for your update, but I still don't know what the expected TODO rules should be added. Do you mean the document should have an example like this SO answer?
|
We don't currently have documentation for every diagnostic, and in those cases the https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/messages.yaml file can be a useful reference. However I believe @bwilkerson For consistency, would it be possible to surface |
The situation here is somewhat less than ideal. In my opinion, the TODO diagnostic really shouldn't be a diagnostic at all. We have made it a diagnostic as a concession to the capabilities of the language server's clients (IDEs). It would be better if IDEs asked for TODOs separately, but they don't. If we were to try to document it, I'm not sure what the documentation would say or how useful it would be. Potentially something like: todo{0} DescriptionThe analyzer produces this diagnostic when it finds a comment in the code that begins with 'TODO', 'FIXME', 'HACK', or 'UNDONE'. ExampleThe following code produces this diagnostic because there is a TODO comment:
Common fixesResolve the TODO. |
Thank you for the link! I’ve found a few undocumented diagnostics in |
@tillulen Do you find @bwilkerson's explanation appropriate? If you have any more specific suggestions, can you please share them? |
Yes, the draft is very useful for me. Most important, its presence in the docs reassures me that Perhaps you could mention the default severity level of I also find these fixes useful:
Normally you don't recommend ignoring lints – and rightly so. The |
The documentation I added to my comment was a hypothetical "this is what it would probably look like if we did add documentation". It doesn't exist anywhere except in the issue comment above. But yes, the
By default, it has a severity of "INFO". If you mean mention it in the docs, we aren't currently documenting the default severity level of any diagnostics, but that's definitely something we could consider.
True. Both IntelliJ and VS Code have support for removing TODO comments from the display.
Those are both reasonable, but I'll point out that they would circumvent your idea of using TODO comments as a signal in your CI/CD. At least the first leaves you with some signal (in the form of an issue); the second hides the problem completely, which might not be what you want. |
For future reference,
|
Yes. Sorry, my wording was not precise. I meant “if
Yes, I thought mentioning the severity in the docs could be useful.
Oh, that’s a helpful feature! I didn’t notice the filter in VS Code. Thank you for mentioning it. (For reference, to filter out all lints that match the string |
Thanks for your response @tillulen. |
I think there might be a misunderstanding. I’ve received the answers to my questions and I appreciate Brian taking the time to clarify things for me. This issue, however, focuses on incorporating those answers into the documentation and making them easily accessible to everyone. If the team decides no documentation updates are planned, closing this issue as Won’t Fix would clearly communicate that decision. Otherwise, please leave it open. |
I think while the documentation/common fixes portion for the todo rule isn't super helpful, having an entry is still helpful in terms of identifying which diagnostics you can configure/ignore. So I'll keep the issue open to track surfacing that improvement. Thanks! |
If the docs have value, then I'm fine with adding them. There isn't any entry in |
Sounds good @bwilkerson, thanks for the context and suggestion. No need to prioritize this on your team's end. When I have a chance, I'll take a look, or someone else who would like to see the issue fixed :) |
Page URL
https://dart.dev/tools/diagnostic-messages.html
Page source
https://github.com/dart-lang/site-www/tree/main/src/tools/diagnostic-messages.md
Describe the problem
The
todo
rule is briefly mentioned on the Customizing static analysis page, but I couldn’t find any reference documentation for the rule.Expected fix
I expected to find further documentation about the
todo
rule either on the Diagnostic messages page or on the Linter rules page.Additional context
The Customizing static analysis page explains how to disable the
todo
rule but does not specify what exactly the rule does.The text was updated successfully, but these errors were encountered: