From: Randy Dunlap <rdunlap@infradead.org>
To: Yueh-Shun Li <shamrocklee@posteo.net>, Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: Irrelevant documentation recommending the use of "include/linux/kernel.h"
Date: Fri, 5 Jan 2024 14:49:14 -0800 [thread overview]
Message-ID: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org> (raw)
In-Reply-To: <bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net>
Hi,
On 12/17/23 15:46, Yueh-Shun Li wrote:
> 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.
>
Yes.
> 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
> ```
the necessary header files in the include/linux/ directory.
>
> or a specific header that contains standalone helper macros?
>
No. That would just end up as another catchall file that
gets too large (bloated) and contain many headers that are not
needed for some or many source files.
> It might be out of scope here,
> but such a header that collects standalone helping macros
> seems non-existent so far.
I think that we don't want another one.
> 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
>
Thanks.
--
#Randy
next prev parent reply other threads:[~2024-01-05 22:49 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-17 23:46 Yueh-Shun Li
2024-01-05 22:49 ` Randy Dunlap [this message]
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=107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org \
--to=rdunlap@infradead.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=shamrocklee@posteo.net \
/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
all inboxes | Powered by JetHome®