From https://gcc.gnu.org/onlinedocs/cpp/Once-Only-Headers.html:
If a header file happens to be included twice, the compiler will process its contents twice. This is very likely to cause an error, e.g. when the compiler sees the same structure definition twice. Even if it does not, it will certainly waste time.
This PR fixes the three headers that have content outside their guards and modifies test/lint/lint-include-guards.py to catch such violations in the future.
A prerequisite for #36808.
<!--e57a25ab6845829454e8d69fc972939a-->
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
<!--006a51241073e994b41acfe9ec718e94-->
<!--021abf342d371248e50ceaed478a90ca-->
See the guideline and AI policy for information on the review process.
| Type | Reviewers |
|---|---|
| Stale ACK | jpk68 |
If your review is incorrectly listed, please copy-paste <code><!--meta-tag:bot-skip--></code> into the comment that the bot should ignore.
<!--5faf32d7da4f0f540f40219e4f7537a3-->
ACK c385c1ff18b5f7e5bb0ff658bc5ba467897904ec
60 | @@ -61,6 +61,27 @@ def _get_header_id(header_file: str) -> str: 61 | return header_id 62 | 63 | 64 | +def _is_comment_or_blank(line: str, in_block_comment: bool) -> tuple[bool, bool]: 65 | + """ Helper function to tell whether a line carries no code. 66 | + 67 | + Args: 68 | + line: A line of the header file. 69 | + in_block_comment: Whether the previous line left a /* ... */ comment open.
We don't use /* comments for the header and we shouldn't start doing that, so this dead logic should be dropped
Sure, but they are wrong, because doxygen doesn't attach them to the guard, but to the next variable:
[DEFAULT_TOR_SOCKS_PORT](https://doxygen.bitcoincore.org/torcontrol_8h.html#a3213ad4529bf3b1a9a0665ce210d19b1) {9050}
Functionality for communicating with Tor.
Implying that this would be possible doesn't seem useful. I guess I missed that there are existing violations, but it may be best to fix them instead of ignoring them?
Without an explicit @file command, Doxygen attached these comments to
the next declaration.
Doxygen treats the word after `@file` as the name of the documented
file and drops it from the text. Use a bare `@file` and `@brief`
instead.
Co-Authored-By: fanquake <fanquake@gmail.com>
Add `@file` and `@brief` so Doxygen documents the file rather than the
`subprocess_close` macro.
Also move the whole comment block inside the include guard. This
simplifies upcoming changes to the include guard linter.
Flag any non-comment line before `#ifndef` or after `#endif`.