Description

Clang-format requires the header guard #ifndef #define HEADER_GUARD_H to be outside of the doxygen documentation, that means outside the @{ ... @} block. If this is not done, then clang-format will indent all preprocessor directives after the #ifndef.
The problem is that the majority of RIOT's header files don't adhere to this order. They either have the header guard inside the doxygen block or the header guard starts correctly outside the doxygen block but the #endif directive is still inside the doxygen documentation.
To fix this inconsistency, I have written a python script that recursively scans all header files in a directory and rearranges the parts, so that the correct order is established.

Previously this issue tracked the effort to bring the header guards into the correct order to work with clang-format. Recently it was decided that from now on, RIOT would use the #pragma once macro instead. This means that some of the previous pull request are outdated and every part of the RIOT repo needs to be updated.

Fixed directories

• drivers drivers: replace header guards with #pragma once #21496, OLD: drivers/include: fixing order of doxygen tags and header guards #21325
• sys: sys: replace header guards with #pragma once #21497 OLD: sys/include: fix headers for clang-format #21340
• cpu: cpu: replace header guards with #pragma once #21501
• core: core: replace header guards with #pragma once #21405
• boards: boards: replace header guards with #pragma once #21504
• examples: examples: replace header guards with #pragma once #21517
• pkg
• tests

Testing procedure

Use my python script and change the path variable 'RIOT_PATH' in the script to whatever directory you want to recursively fix the header files.
Warning: the script isn't fool-proof but fixes 95% of all header files that have this issue. There are individual issues with the formatting that require manual intervention.

The script can be found here

Application

This is based on the fix in #20905 addressed by @mguetschow but with the added benefit of keeping the blocks balanced.