style: Inconsistent macro names changed

[rruuaanng]

Fix incorrect header file pre-macro names in
include/zephyr/dt-bindings.

[kartben]

@rruuaanng needs rebase

[de-nordic]

Ha, so that is where the file comes from..

[kartben]

@rruuaanng conflicts once again and needs rebase:) thanks!

[kartben]

@soburi @ajf58 can you please look into the CI failure? Not sure why this wasn't caught on main, but this looks related to yesterday's Pico2 changes? Thanks!

[soburi]

Is this rebased from before #83343 commits?
I think this PR is a fix for the include guard,
but for
include/zephyr/dt-bindings/pinctrl/rpi-pico-rp2040-pinctrl.h
it looks like not only it.
It seems also contains revert #83343 changes.

[rruuaanng]

@kartben I have fixed it, I will raise a PR later, hope it helps.

Edit

diff

-#define RP2XXX_PINMUX(pin_num, alt_func) (pin_num << RP2_PIN_NUM_POS | alt_func << RP2_ALT_FUNC_POS)
+#define RP2XXX_PINMUX(pin_num, alt_func) ((pin_num << RP2_PIN_NUM_POS) \
+                                        | (alt_func << RP2_ALT_FUNC_POS))

It looks like the parser is parsing << as a symbol instead of an operator.

[ajf58]

Relates to #80781 .

@rruuaanng In the commit message:

Fix incorrect header file pre-macro names in
'include/zephyr/dt-bindings'.

1. I've never seen include guards referred to as "pre-macro names", and it's a bit close to "predefined macros" which is something else entirely. Please consider rephrasing this.
2. When you say "incorrect", what do you mean by that? I don't think that the project has any documentation that defines this, and it's challenging for contributors to know what's right or wrong without this information. Can you refer to it in the PR and/or commit message, or update the documentation?

[rruuaanng]

Congratulations on discovering an interesting point. In fact, this is just a convention in Zephyr. For some challenging subsystems, typical contributors and maintainers, who usually have extensive experience, choose to follow the project's conventions. However, there are currently some subsystems synchronized from authoritative upstream projects, such as Xen. If the include guard macro names for these subsystems were to follow the convention, they would also be incorrect. I believe that when fixing other macros that need synchronization, we should not include the correct or conventional names in the commit messages (this is usually the case).

But I'm willing to modify the commit information. It does look a little vague.

[ajf58]

@rruuaanng

Making things consistent is great, following a consistent pattern is also great, no disagreement at all from me.

We do need to be mindful, however, that we don't lean hard on unwritten rules of right/wrong, correct/incorrect, and I feel we can use these kinds of PRs as opportunities to improve the documentation. The implicit rule is "swap include/zephyr for zephyr/include, convert non-alpha characters to underscores, capitalize, add a _H_ suffix." Quite a mouthful, and the swapping step is a bit a of mystery to me.

[rruuaanng]

@ajf58 Since that’s the case, are you interested in supplementing the documentation? Perhaps these guidelines should be included in the contribution guide?

[ajf58]

are you interested in supplementing the documentation?

In general, yes.

Perhaps these guidelines should be included in the contribution guide?

I agree, this matches one of my suggestions in #80781 .

Currently the documentation says follow the Linux kernel style guides, which does not specify what pattern include guards take. #define BANANA_DISCO_UNIQUE_ANYTHING_WITHOUT_SUFFIX would be valid, if not intuitive.

If there's some agreement about what is The One True include guard style, I'm happy to update the docs, but as mentioned in #80781 , some folders have multiple conflicting styles, and there's no way to tell which, if any, is correct.