Irrelevant documentation recommending the use of "include/linux/kernel.h"

Irrelevant documentation recommending the use of "include/linux/kernel.h"

[Yueh-Shun Li]

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

Re: Irrelevant documentation recommending the use of "include/linux/kernel.h"

[Randy Dunlap]

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

[PATCH 0/4] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

Dear Maintainers,

This series of patches targets the "Linux kernel coding style"
documentation and recommend reusing macros inside the include/linux
directory instead of the obsolete header "include/linux/kernel.h".

This addresses the issue 'Irrelevant documentation recommending the use
of "include/linux/kernel.h"'[1][2] and help deprecating "kernel.h".

If applied, developers will no longer be confused by the contradiction
between "Linux kernel style guide" suggestions and the deprecation
notice on top of "kernel.h".

There's also a patch that adds an example to show how reusing macro
definition from shared headers help prevent naming collisions.

This series contains the update to the zh_TW and zh_CN translation of
the corresponding documentation changes.

Best regards,

Shamrock

[1]: https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
[2]: https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/

Yueh-Shun Li (4):
  coding-style: recommend split headers instead of kernel.h
  coding-style: show how reusing macros prevents naming collisions
  doc/zh_TW: coding-style: update content for section 18
  doc/zh_CN: coding-style: update content of section 18

 Documentation/process/coding-style.rst        | 41 +++++++++++++++----
 .../zh_CN/process/coding-style.rst            | 39 ++++++++++++++----
 .../zh_TW/process/coding-style.rst            | 39 ++++++++++++++----
 3 files changed, 95 insertions(+), 24 deletions(-)

-- 
2.42.0

[PATCH 1/4] coding-style: recommend split headers instead of kernel.h

[Yueh-Shun Li]

In section "18) Don't re-invent the kernel macros" in "Linux kernel
coding style":

Recommend reusing macros from headers inside include/linux, instead of
the obsolete include/linux/kernel.h

Change wording

- "The header file contains macros" -> "the header files provide macros"
  Some macros are intended to use inside the header file only, or are
  considered the implementation detail of other facilities. Developers
  are expected to determine if a macro is meant to be used outside the
  header file.

Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
---
 Documentation/process/coding-style.rst | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 6db37a46d305..2504cb00a961 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1048,27 +1048,30 @@ readable alternative if the call-sites have naked true/false constants.
 Otherwise limited use of bool in structures and arguments can improve
 readability.
 
+
 18) Don't re-invent the kernel macros
 -------------------------------------
 
-The header file include/linux/kernel.h contains a number of macros that
-you should use, rather than explicitly coding some variant of them yourself.
+The header files in the ``include/linux`` directory provide a number of macros
+that you should use, rather than explicitly coding some variant of them
+yourself.
+
 For example, if you need to calculate the length of an array, take advantage
-of the macro
+of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by
 
 .. code-block:: c
 
-	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+	#include <linux/array_size.h>
+	ARRAY_SIZE(x) // The size of array x
 
 Similarly, if you need to calculate the size of some structure member, use
+``sizeof_field()`` from ``include/linux/stddef.h``.
 
-.. code-block:: c
-
-	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
+There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
+that do strict type checking if you need them.
 
-There are also min() and max() macros that do strict type checking if you
-need them.  Feel free to peruse that header file to see what else is already
-defined that you shouldn't reproduce in your code.
+Feel free to search across and peruse the header files to see what else is
+already defined that you shouldn't reproduce in your code.
 
 
 19) Editor modelines and other cruft
-- 
2.42.0

[PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Yueh-Shun Li]

In section "18) Don't re-invent the kernel macros" in "Linux kernel
coding style":

Show how reusing macros from shared headers prevents naming collisions
using "stringify", the one of the most widely reinvented macro, as an
example.

This patch aims to provide a stronger reason to reuse shared macros,
by showing the risk of improvised macro variants.

Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
---
 Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 2504cb00a961..1e79aba4b346 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of some structure member, use
 There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
 that do strict type checking if you need them.
 
+Using existing macros provided by the shared headers also prevents naming
+collisions. For example, if one developer define in ``foo.h``
+
+.. code-block:: c
+
+	#define __stringify(x) __stringify_1(x)
+	#define __stringify_1(x) #x
+
+and another define in ``bar.h``
+
+.. code-block:: c
+
+	#define stringify(x) __stringify(x)
+	#define __stringify(x) #x
+
+When both headers are ``#include``-d into the same file, the facilities provided
+by ``foo.h`` might be broken by ``bar.h``.
+
+If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` provided by
+``include/linux/stringify.h``, they wouldn't have stepped onto each other's
+toes.
+
 Feel free to search across and peruse the header files to see what else is
 already defined that you shouldn't reproduce in your code.
 
-- 
2.42.0

[PATCH 3/4] doc/zh_TW: coding-style: update content for section 18

[Yueh-Shun Li]

Update the content of the zh_TW translation of "Linux kernel coding
style" section 18, following the change proposed in the first 2 patches
in these patch series.

From the diff of between the zh_TW and zh_CN translation of the file
coding-style.rst, it seems that the zh_TW files are direct
character-by-character translation of the zh_CN files, without any
phrase localization. This results in wording unfamilliar to zh_TW
speakers.

This patch reuses existing terms inside coding-style.rst (e.g. 宏 for
"macros" and 頭文件 for "header files"), while localizing terms
introduced in this file the first time (e.g. 搜尋 instead of 搜索 for
"search").

The localization of Chinese dialects could be performed programmatically
with the help of OpenCC[1] with custom configuration based on the
upstream s2twp.json (zh_CN to zh_TW with Taiwanese idiom), but that is
beyond the scope of this patch.

[1]: https://github.com/BYVoid/OpenCC

Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
---
 .../zh_TW/process/coding-style.rst            | 39 +++++++++++++++----
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index 5749363de421..0197405cfec8 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -922,25 +922,48 @@ Linux內核布爾（bool）類型是C99 _Bool類型的別名。布爾值只能
 
 總之，在結構體和參數中有限地使用布爾可以提高可讀性。
 
+
 18) 不要重新發明內核宏
 ----------------------
 
-頭文件 include/linux/kernel.h 包含了一些宏，你應該使用它們，而不要自己寫一些
-它們的變種。比如，如果你需要計算一個數組的長度，使用這個宏
+``include/linux`` 目錄下的頭文件提供了一些宏，你應該使用它們，而不要自己寫
+一些它們的變種。比如，如果你需要計算一個數組的長度，使用
+``include/linux/array_size.h`` 提供的 ``ARRAY_SIZE()`` 宏
 
 .. code-block:: c
 
-	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+	#include <linux/array_size.h>
+	ARRAY_SIZE(x) // The size of array x
+
+類似的，如果你要計算某結構體成員的大小，使用 ``include/linux/stddef.h`` 當
+中的 ``sizeof_field()`` 宏。
+
+還有 ``include/linux/minmax.h`` 提供能做嚴格的類型檢查的 ``min()`` 和
+``max()`` 宏，如果你需要可以使用它們。
 
-類似的，如果你要計算某結構體成員的大小，使用
+使用共用頭文件所提供的宏也能避免命名衝突。比如說，如果有個開發者在頭文件
+``foo.h`` 中定義了
 
 .. code-block:: c
 
-	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
+	#define __stringify(x) __stringify_1(x)
+	#define __stringify_1(x) #x
+
+但另一個開發者在頭文件 ``bar.h`` 中定義了
+
+.. code-block:: c
+
+	#define stringify(x) __stringify(x)
+	#define __stringify(x) #x
+
+當兩個頭文件都被 ``#include`` 進同一份文件，``foo.h`` 提供的工具可能會被
+``bar.h`` 破壞。
+
+如果兩個頭文件都使用 ``include/linux/stringify.h`` 提供的 ``__stringify()``
+宏，就不會互相干擾了。
 
-還有可以做嚴格的類型檢查的 min() 和 max() 宏，如果你需要可以使用它們。你可以
-自己看看那個頭文件裏還定義了什麼你可以拿來用的東西，如果有定義的話，你就不應
-在你的代碼裏自己重新定義。
+你可以自己搜尋、看看那些頭文件裏還定義了什麼你可以拿來用的東西，如果有定義的
+話，你就不應在你的代碼裏自己重新定義。
 
 
 19) 編輯器模式行和其他需要羅嗦的事情
-- 
2.42.0

[PATCH 4/4] doc/zh_CN: coding-style: update content of section 18

[Yueh-Shun Li]

Update the content of the zh_CN translation of "Linux kernel coding
style" section 18, following the change proposed in the first 2 patches
in these patch series.

As a zh_TW speaker, I tried my best to compare and proofread the content
generated with OpenCC[1] with tw2s and tw2sp configurations, and
existing translation in the same file. Please kindly point out anything
I should fix.

[1]: https://github.com/BYVoid/OpenCC

Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
---
 .../zh_CN/process/coding-style.rst            | 39 +++++++++++++++----
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index fa28ef0a7fee..14ff3cdc2d0d 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -919,25 +919,48 @@ Linux内核布尔（bool）类型是C99 _Bool类型的别名。布尔值只能
 
 总之，在结构体和参数中有限地使用布尔可以提高可读性。
 
+
 18) 不要重新发明内核宏
 ----------------------
 
-头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些
-它们的变种。比如，如果你需要计算一个数组的长度，使用这个宏
+``include/linux`` 目录下的头文件提供了一些宏，你应该使用它们，而不要自己写
+一些它们的变种。比如，如果你需要计算一个数组的长度，使用
+``include/linux/array_size.h`` 提供的 ``ARRAY_SIZE()`` 宏
 
 .. code-block:: c
 
-	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+	#include <linux/array_size.h>
+	ARRAY_SIZE(x) // The size of array x
+
+类似的，如果你要计算某结构体成员的大小，使用 ``include/linux/stddef.h`` 当
+中的 ``sizeof_field()`` 宏。
+
+还有 ``include/linux/minmax.h`` 提供能做严格的类型检查的 ``min()`` 和
+``max()`` 宏，如果你需要可以使用它们。
 
-类似的，如果你要计算某结构体成员的大小，使用
+使用共用头文件所提供的宏也能避免命名冲突。比如说，如果有个开发者在头文件
+``foo.h`` 中定义了
 
 .. code-block:: c
 
-	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
+	#define __stringify(x) __stringify_1(x)
+	#define __stringify_1(x) #x
+
+但另一个开发者在头文件 ``bar.h`` 中定义了
+
+.. code-block:: c
+
+	#define stringify(x) __stringify(x)
+	#define __stringify(x) #x
+
+当两个头文件都被 ``#include`` 进同一份文件，``foo.h`` 提供的工具可能会被
+``bar.h`` 破坏。
+
+如果两个头文件都使用 ``include/linux/stringify.h`` 提供的 ``__stringify()``
+宏，就不会互相干扰了。
 
-还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以
-自己看看那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应
-在你的代码里自己重新定义。
+你可以自己搜索、看看那些头文件里还定义了什么你可以拿来用的东西，如果有定义的
+话，你就不应在你的代码里自己重新定义。
 
 
 19) 编辑器模式行和其他需要罗嗦的事情
-- 
2.42.0

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li <shamrocklee@posteo.net> writes:

> In section "18) Don't re-invent the kernel macros" in "Linux kernel
> coding style":
>
> Show how reusing macros from shared headers prevents naming collisions
> using "stringify", the one of the most widely reinvented macro, as an
> example.
>
> This patch aims to provide a stronger reason to reuse shared macros,
> by showing the risk of improvised macro variants.
>
> Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
> ---
>  Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 2504cb00a961..1e79aba4b346 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of some structure member, use
>  There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
>  that do strict type checking if you need them.
>  
> +Using existing macros provided by the shared headers also prevents naming
> +collisions. For example, if one developer define in ``foo.h``
> +
> +.. code-block:: c
> +
> +	#define __stringify(x) __stringify_1(x)
> +	#define __stringify_1(x) #x
> +
> +and another define in ``bar.h``
> +
> +.. code-block:: c
> +
> +	#define stringify(x) __stringify(x)
> +	#define __stringify(x) #x
> +
> +When both headers are ``#include``-d into the same file, the facilities provided
> +by ``foo.h`` might be broken by ``bar.h``.
> +
> +If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` provided by
> +``include/linux/stringify.h``, they wouldn't have stepped onto each other's
> +toes.
> +

So everything we add to our documentation has a cost in terms of reader
attention.  We ask people to read through a lot of material now, and
should only increase that ask for good reason.

With that context, I have to wonder whether we really need to tell our
readers, who are supposed to be capable developers, that reuse can help
to avoid name collisions?

Thanks,

jon

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Yueh-Shun Li]

Dear Mr. Corbet,

Thank you very much for your feed back.

On 2024-01-09 00:28, Jonathan Corbet wrote:
> Yueh-Shun Li <shamrocklee@posteo.net> writes:
> 
>> In section "18) Don't re-invent the kernel macros" in "Linux kernel
>> coding style":
>> 
>> Show how reusing macros from shared headers prevents naming collisions
>> using "stringify", the one of the most widely reinvented macro, as an
>> example.
>> 
>> This patch aims to provide a stronger reason to reuse shared macros,
>> by showing the risk of improvised macro variants.
>> 
>> Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
>> ---
>>  Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++
>>  1 file changed, 22 insertions(+)
>> 
>> diff --git a/Documentation/process/coding-style.rst 
>> b/Documentation/process/coding-style.rst
>> index 2504cb00a961..1e79aba4b346 100644
>> --- a/Documentation/process/coding-style.rst
>> +++ b/Documentation/process/coding-style.rst
>> @@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of 
>> some structure member, use
>>  There are also ``min()`` and ``max()`` macros in 
>> ``include/linux/minmax.h``
>>  that do strict type checking if you need them.
>> 
>> +Using existing macros provided by the shared headers also prevents 
>> naming
>> +collisions. For example, if one developer define in ``foo.h``
>> +
>> +.. code-block:: c
>> +
>> +	#define __stringify(x) __stringify_1(x)
>> +	#define __stringify_1(x) #x
>> +
>> +and another define in ``bar.h``
>> +
>> +.. code-block:: c
>> +
>> +	#define stringify(x) __stringify(x)
>> +	#define __stringify(x) #x
>> +
>> +When both headers are ``#include``-d into the same file, the 
>> facilities provided
>> +by ``foo.h`` might be broken by ``bar.h``.
>> +
>> +If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` 
>> provided by
>> +``include/linux/stringify.h``, they wouldn't have stepped onto each 
>> other's
>> +toes.
>> +
> 
> So everything we add to our documentation has a cost in terms of reader
> attention.  We ask people to read through a lot of material now, and
> should only increase that ask for good reason.
> 
> With that context, I have to wonder whether we really need to tell our
> readers, who are supposed to be capable developers, that reuse can help
> to avoid name collisions?
> 

The motivation comes from existing inconsistency of the "__stringify()" 
macro
definition between e.g. "samples/bpf/tracex5.bpf.c" and other files.

I agree that increasing the length of the documentation without 
substantial
benefits would not be helpful for the readers, and doubling the length 
of a
section is too much for its purpose.

Should I shorten it into one sentence, like

```
On the other hand, locally-defined variants, such as ``#define 
__stringify(x) #x``,
could lead to naming collisions that break otherwise functioning 
facilities.
```

or just omit it in the next version of patches?

> Thanks,
> 
> jon

Thank you for your time and guidance.

Shamrock

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li <shamrocklee@posteo.net> writes:

>> So everything we add to our documentation has a cost in terms of reader
>> attention.  We ask people to read through a lot of material now, and
>> should only increase that ask for good reason.
>> 
>> With that context, I have to wonder whether we really need to tell our
>> readers, who are supposed to be capable developers, that reuse can help
>> to avoid name collisions?
>> 
>
> The motivation comes from existing inconsistency of the "__stringify()" 
> macro
> definition between e.g. "samples/bpf/tracex5.bpf.c" and other files.
>
> I agree that increasing the length of the documentation without
> substantial benefits would not be helpful for the readers, and
> doubling the length of a section is too much for its purpose.
>
> Should I shorten it into one sentence, like
>
> ```
> On the other hand, locally-defined variants, such as ``#define 
> __stringify(x) #x``,
> could lead to naming collisions that break otherwise functioning 
> facilities.
> ```
>
> or just omit it in the next version of patches?

My own feeling (others may well disagree) is that this isn't worth
mentioning in the coding-style document.  What you *could* do is to fix
the redefinitions (if that hasn't happened yet) and make sure that the
macros in question are covered in our kernel documentation.

Thanks,

jon

[PATCH v2 0/3] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

Dear Maintainers,

In this version of patch series, I drop the patch abouth the nameing
conflicts caused by locally-defined macro variants to streamline the
documentation.[1]

This series of patches targets the "Linux kernel coding style"
documentation and recommend reusing macros inside the include/linux
directory instead of the obsolete header "include/linux/kernel.h".

This addresses the issue 'Irrelevant documentation recommending the use
of "include/linux/kernel.h"'[2][3] and help deprecating "kernel.h".

This series contains the update to the zh_TW and zh_CN translation of
the corresponding documentation changes.

Best regards,

Shamrock

[1]: https://lore.kernel.org/linux-doc/87ederwuid.fsf@meer.lwn.net/
[2]: https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
[3]: https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/

Yueh-Shun Li (3):
  coding-style: recommend split headers instead of kernel.h
  doc/zh_TW: coding-style: update content for section 18
  doc/zh_CN: coding-style: update content of section 18

 Documentation/process/coding-style.rst        | 24 ++++++++++---------
 .../zh_CN/process/coding-style.rst            | 22 ++++++++---------
 .../zh_TW/process/coding-style.rst            | 22 ++++++++---------
 3 files changed, 35 insertions(+), 33 deletions(-)

-- 
2.42.0

Re: [PATCH v2 0/3] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

On 2024-01-09 03:37, Yueh-Shun Li wrote:
> Dear Maintainers,
> 
> In this version of patch series, I drop the patch abouth the nameing
> conflicts caused by locally-defined macro variants to streamline the
> documentation.[1]
> 
> This series of patches targets the "Linux kernel coding style"
> documentation and recommend reusing macros inside the include/linux
> directory instead of the obsolete header "include/linux/kernel.h".
> 
> This addresses the issue 'Irrelevant documentation recommending the use
> of "include/linux/kernel.h"'[2][3] and help deprecating "kernel.h".
> 
> This series contains the update to the zh_TW and zh_CN translation of
> the corresponding documentation changes.
> 
> Best regards,
> 
> Shamrock
> 
> [1]: https://lore.kernel.org/linux-doc/87ederwuid.fsf@meer.lwn.net/
> [2]:
> https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
> [3]:
> https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/
> 
> Yueh-Shun Li (3):
>   coding-style: recommend split headers instead of kernel.h
>   doc/zh_TW: coding-style: update content for section 18
>   doc/zh_CN: coding-style: update content of section 18
> 
>  Documentation/process/coding-style.rst        | 24 ++++++++++---------
>  .../zh_CN/process/coding-style.rst            | 22 ++++++++---------
>  .../zh_TW/process/coding-style.rst            | 22 ++++++++---------
>  3 files changed, 35 insertions(+), 33 deletions(-)

This series of patches didn't make it to the lists due to my loose ends.
Sorry for the noise.

Sincerely,

Shamrock

[PATCH v3 0/1] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

Dear Maintainers,

This patch targets the "Linux kernel coding style" documentation and
recommend reusing macros inside the include/linux directory instead of
the obsolete header "include/linux/kernel.h".

This addresses the issue 'Irrelevant documentation recommending the use
of "include/linux/kernel.h"'[1][2] and help deprecating "kernel.h".

Changes in this roll:

Drop the patch mentioning the naming collisions caused by
locally-defined macro variants.[3]

Drop the patches that updates the zh_TW and zh_CN translation. I'll
send them again once the change of the untranslated documentation gets
ready.

Best regards,

Shamrock

[1]: https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
[2]: https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/
[3]: https://lore.kernel.org/linux-doc/87ederwuid.fsf@meer.lwn.net/

Yueh-Shun Li (1):
  coding-style: recommend split headers instead of kernel.h

 Documentation/process/coding-style.rst | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

-- 
2.42.0

[PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

[Yueh-Shun Li]

In section "18) Don't re-invent the kernel macros" in "Linux kernel
coding style":

Recommend reusing macros from headers inside include/linux, instead of
the obsolete include/linux/kernel.h

Change wording

- "The header file contains macros" -> "the header files provide macros"
  Some macros are intended to use inside the header file only, or are
  considered the implementation detail of other facilities. Developers
  are expected to determine if a macro is meant to be used outside the
  header file.

Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
---
 Documentation/process/coding-style.rst | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 6db37a46d305..2a5c4f4c568c 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1048,27 +1048,29 @@ readable alternative if the call-sites have naked true/false constants.
 Otherwise limited use of bool in structures and arguments can improve
 readability.
 
+
 18) Don't re-invent the kernel macros
 -------------------------------------
 
-The header file include/linux/kernel.h contains a number of macros that
-you should use, rather than explicitly coding some variant of them yourself.
+The header files in the ``include/linux`` directory provide a number of macros
+that you should use, rather than explicitly coding some variant of them
+yourself.
+
 For example, if you need to calculate the length of an array, take advantage
-of the macro
+of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by
 
 .. code-block:: c
 
-	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+	#include <linux/array_size.h>
+	ARRAY_SIZE(x) // The size of array x
 
 Similarly, if you need to calculate the size of some structure member, use
+``sizeof_field()`` from ``include/linux/stddef.h``.
 
-.. code-block:: c
-
-	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
-
-There are also min() and max() macros that do strict type checking if you
-need them.  Feel free to peruse that header file to see what else is already
-defined that you shouldn't reproduce in your code.
+There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
+that do strict type checking if you need them. Feel free to search across and
+peruse the header files to see what else is already defined that you shouldn't
+reproduce in your code.
 
 
 19) Editor modelines and other cruft
-- 
2.42.0

Re: [PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

[Randy Dunlap]

On 1/8/24 12:22, Yueh-Shun Li wrote:
> In section "18) Don't re-invent the kernel macros" in "Linux kernel
> coding style":
> 
> Recommend reusing macros from headers inside include/linux, instead of
> the obsolete include/linux/kernel.h
> 
> Change wording
> 
> - "The header file contains macros" -> "the header files provide macros"
>   Some macros are intended to use inside the header file only, or are
>   considered the implementation detail of other facilities. Developers
>   are expected to determine if a macro is meant to be used outside the
>   header file.
> 
> Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.

> ---
>  Documentation/process/coding-style.rst | 24 +++++++++++++-----------
>  1 file changed, 13 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 6db37a46d305..2a5c4f4c568c 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1048,27 +1048,29 @@ readable alternative if the call-sites have naked true/false constants.
>  Otherwise limited use of bool in structures and arguments can improve
>  readability.
>  
> +
>  18) Don't re-invent the kernel macros
>  -------------------------------------
>  
> -The header file include/linux/kernel.h contains a number of macros that
> -you should use, rather than explicitly coding some variant of them yourself.
> +The header files in the ``include/linux`` directory provide a number of macros
> +that you should use, rather than explicitly coding some variant of them
> +yourself.
> +
>  For example, if you need to calculate the length of an array, take advantage
> -of the macro
> +of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by
>  
>  .. code-block:: c
>  
> -	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
> +	#include <linux/array_size.h>
> +	ARRAY_SIZE(x) // The size of array x
>  
>  Similarly, if you need to calculate the size of some structure member, use
> +``sizeof_field()`` from ``include/linux/stddef.h``.
>  
> -.. code-block:: c
> -
> -	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
> -
> -There are also min() and max() macros that do strict type checking if you
> -need them.  Feel free to peruse that header file to see what else is already
> -defined that you shouldn't reproduce in your code.
> +There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
> +that do strict type checking if you need them. Feel free to search across and
> +peruse the header files to see what else is already defined that you shouldn't
> +reproduce in your code.
>  
>  
>  19) Editor modelines and other cruft

-- 
#Randy

Re: [PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

[Yueh-Shun Li]

On 2024-01-28 14:26, Randy Dunlap wrote:
> On 1/8/24 12:22, Yueh-Shun Li wrote:
> > In section "18) Don't re-invent the kernel macros" in "Linux kernel
> > coding style":
> >
> > Recommend reusing macros from headers inside include/linux, instead of
> > the obsolete include/linux/kernel.h
> >
> > Change wording
> >
> > - "The header file contains macros" -> "the header files provide macros"
> >   Some macros are intended to use inside the header file only, or are
> >   considered the implementation detail of other facilities. Developers
> >   are expected to determine if a macro is meant to be used outside the
> >   header file.
> >
> > Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
> 
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> Thanks.
> 

Thank you for acknowledging.

Anything I could help to push it forward?

> > ---
> >  Documentation/process/coding-style.rst | 24 +++++++++++++-----------
> >  1 file changed, 13 insertions(+), 11 deletions(-)
> >
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > index 6db37a46d305..2a5c4f4c568c 100644
> > --- a/Documentation/process/coding-style.rst
> > +++ b/Documentation/process/coding-style.rst
> > @@ -1048,27 +1048,29 @@ readable alternative if the call-sites have naked true/false constants.
> >  Otherwise limited use of bool in structures and arguments can improve
> >  readability.
> >
> > +
> >  18) Don't re-invent the kernel macros
> >  -------------------------------------
> >
> > -The header file include/linux/kernel.h contains a number of macros that
> > -you should use, rather than explicitly coding some variant of them yourself.
> > +The header files in the ``include/linux`` directory provide a number of macros
> > +that you should use, rather than explicitly coding some variant of them
> > +yourself.
> > +
> >  For example, if you need to calculate the length of an array, take advantage
> > -of the macro
> > +of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by
> >
> >  .. code-block:: c
> >
> > -	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
> > +	#include <linux/array_size.h>
> > +	ARRAY_SIZE(x) // The size of array x
> >
> >  Similarly, if you need to calculate the size of some structure member, use
> > +``sizeof_field()`` from ``include/linux/stddef.h``.
> >
> > -.. code-block:: c
> > -
> > -	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
> > -
> > -There are also min() and max() macros that do strict type checking if you
> > -need them.  Feel free to peruse that header file to see what else is already
> > -defined that you shouldn't reproduce in your code.
> > +There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
> > +that do strict type checking if you need them. Feel free to search across and
> > +peruse the header files to see what else is already defined that you shouldn't
> > +reproduce in your code.
> >
> >
> >  19) Editor modelines and other cruft

Best regards,

Yueh-Shun