mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
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

  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®