dist/tools/compile_commands: add -Wdocumentation for --clangd#22450
Conversation
maribu
added
Type: enhancement
| pass | ||
|
|
||
| if args.clangd: | ||
| # Inject flags for better UX if compile commands are intended to be |
There was a problem hiding this comment.
Not sure what you mean with better UX?
There was a problem hiding this comment.
user experience
The first flag removes warnings about GCC-only flags like -mlong-jump for Xtensa. The second results in Doxygen markup being checked. The third disables warnings about missing __attribute__((deprecated))`` in case an @deprecated` is found in the Doxygen markup.
IMO we should add __attribute__((dreprecated)), but until we actually do that, the warning will be just noise.
There was a problem hiding this comment.
Oh, I just wondered what "UX" means.
But perhaps you can add a comment to the Dr. Dre precated flag that it should be removed when __attribute__(Dr.Dreprecated)) are added to all relevant functions.
Perhaps we should also document the deprecation process somewhere, but that's not like a rabbit hole I feel like getting into today :/
maribu
force-pushed
the
tools/compile-commands/warn-doc
branch
from
d4318d3 to
e7396f0
Compare
crasbe
left a comment
crasbe
left a comment
There was a problem hiding this comment.
Looks good, please squash :)
In case the user called with `--clangd`, we should try to give the best linting experience to users. Adding `-Wdocumentation` is particularly helpful for writing Doxygen markup, as it will directly in the editor point out when e.g. `@param <key>` is not matching any of the arguments. Co-authored-by: crasbe <crasbe@gmail.com>
maribu
force-pushed
the
tools/compile-commands/warn-doc
branch
from
955cae7 to
c10854e
Compare
|
The check labels workflow won't run if you've enabled Automerge before the last squash. That's a consequence of the reduced triggering and therefore the reduced email spam 😅 |
|
Thx :) |
3 participants
Contribution description
In case the user called with
--clangd, we should try to give the best linting experience to users. Adding-Wdocumentationis particularly helpful for writing Doxygen markup, as it will directly in the editor point out when e.g.@param <key>is not matching any of the arguments.Testing procedure
Run
make compile-commands, then open a header in a clangd enabled editor and rename a function parameter without changing the the corresponding@param. Now the editor should remind you to keep the parameter in sync.Issues/PRs references
None
Declaration of AI-Tools / LLMs usage:
AI-Tools / LLMs that were used are: