From: Yueh-Shun Li <shamrocklee@posteo.net>
To: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Irrelevant documentation recommending the use of "include/linux/kernel.h"
Date: Sun, 17 Dec 2023 23:46:06 +0000 [thread overview]
Message-ID: <bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net> (raw)
Dear Maintainer,
The section "18) Don't re-invent the kernel macros" in
"Linux kernel coding style" (Documentation/process/coding-style.rst)
recommends re-using the macros defined in "include/linux/kernel.h"
instead of the improvised ones locally.
However, There's a note in the comment block added by commit
40cbf09f060c
("kernel.h: include a note to discourage people from including it in
headers")
two years ago, saying that there's an in-progress splitting of kernel.h
and inclusion in headers under include/ is discouraged.
Considering that the section was added 17 years ago by commit
58637ec90b7c
("Add a new section to CodingStyle, promoting include/linux/kernel.h"),
the section about kernel.h in the "Linux kernel coding style"
documentation seems outdated.
Reproduction steps:
```sh
# cd to the kernel source tree
cd path/to/source/linux
# Show the git blame of the documentation section added in 2006
git blame -L 1051,1071 Documentation/process/coding-style.rst
# Show the comment note on top of include/linux/kernel.h added in 2022
git blame -L 2,10 include/linux/kernel.h
```
Should we change
```
The header file include/linux/kernel.h
```
to something like
```
The header files under the include/linux/ directory
```
or a specific header that contains standalone helper macros?
It might be out of scope here,
but such a header that collects standalone helping macros
seems non-existent so far.
It would be great to have one that contains things like
"STRINGIFY", "CONCATENATE" (or "PASTE"), "UNIQUE_ID"
and other helper macros without external dependencies.
There's one called "include/linux/util_macros.h", but it depends on
"include/linux/math.h".
It's the first time for me to report an issue in LKML.
Please kindly point out anything
that I should fix or could improve.
Best regards,
Shamrock
next reply other threads:[~2023-12-17 23:46 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-17 23:46 Yueh-Shun Li [this message]
2024-01-05 22:49 ` Irrelevant documentation recommending the use of "include/linux/kernel.h" Randy Dunlap
2024-01-08 16:03 ` [PATCH 0/4] coding-style: recommend reusing macros from split headers instead of kernel.h Yueh-Shun Li
2024-01-08 16:03 ` [PATCH 1/4] coding-style: recommend " Yueh-Shun Li
2024-01-08 16:03 ` [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions Yueh-Shun Li
2024-01-08 16:28 ` Jonathan Corbet
2024-01-08 18:23 ` Yueh-Shun Li
2024-01-08 18:27 ` Jonathan Corbet
2024-01-08 16:03 ` [PATCH 3/4] doc/zh_TW: coding-style: update content for section 18 Yueh-Shun Li
2024-01-08 16:03 ` [PATCH 4/4] doc/zh_CN: coding-style: update content of " Yueh-Shun Li
2024-01-08 19:37 ` [PATCH v2 0/3] coding-style: recommend reusing macros from split headers instead of kernel.h Yueh-Shun Li
2024-01-08 20:17 ` Yueh-Shun Li
2024-01-08 20:18 ` [PATCH v3 0/1] " Yueh-Shun Li
2024-01-08 20:22 ` [PATCH v3 1/1] coding-style: recommend " Yueh-Shun Li
2024-01-28 6:26 ` Randy Dunlap
2024-05-06 23:17 ` Yueh-Shun Li
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net \
--to=shamrocklee@posteo.net \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).