[PATCH] docs: kernel-doc.rst: move label "_kernel_doc" to top

[PATCH] docs: kernel-doc.rst: move label "_kernel_doc" to top

[Wu XiangCheng]

From: Wu XiangCheng <bobwxc@email.cn>

"_kernel_doc" label which should refer to the entire document was in the
middle, move it to top. Also fix zh translation.

Fixes: 46347502b099 ("Restructure kernel-doc.rst")
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
---
 Documentation/doc-guide/kernel-doc.rst                    | 3 ++-
 Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 9c779bd7a751..e494f907231e 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,5 +1,7 @@
 .. title:: Kernel-doc comments
 
+.. _kernel_doc:
+
 ===========================
 Writing kernel-doc comments
 ===========================
@@ -525,7 +527,6 @@ The kernel-doc extension is included in the kernel source tree, at
 ``scripts/kernel-doc`` script to extract the documentation comments from the
 source.
 
-.. _kernel_doc:
 
 How to use kernel-doc to generate man pages
 -------------------------------------------
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index ccfb9b8329c2..48aad9868d4c 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -4,6 +4,8 @@
 
 :译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
 
+.. _kernel_doc_zh:
+
 编写kernel-doc注释
 ==================
 
@@ -475,7 +477,6 @@ doc: *title*
 kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
 在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
 
-.. _kernel_doc_zh:
 
 如何使用kernel-doc生成手册（man）页
 -----------------------------------
-- 
2.30.2

Re: [PATCH] docs: kernel-doc.rst: move label "_kernel_doc" to top

[Jonathan Corbet]

Wu XiangCheng <wu.xiangcheng@linux.dev> writes:

> From: Wu XiangCheng <bobwxc@email.cn>
>
> "_kernel_doc" label which should refer to the entire document was in the
> middle, move it to top. Also fix zh translation.
>
> Fixes: 46347502b099 ("Restructure kernel-doc.rst")
> Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
> ---
>  Documentation/doc-guide/kernel-doc.rst                    | 3 ++-
>  Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 3 ++-
>  2 files changed, 4 insertions(+), 2 deletions(-)

Rather than do this, is there any reason to not just delete the label
entirely?  If anything references it, it can just name the file instead.
But, as it happens, it's not even referenced anywhere...

Thanks,

jon

Re: [PATCH] docs: kernel-doc.rst: move label "_kernel_doc" to top

[Wu XiangCheng]

话说 Jonathan Corbet 于 2022-08-13 (六) 10:53:13 -0600 曰过：
> Wu XiangCheng <wu.xiangcheng@linux.dev> writes:
> 
> > From: Wu XiangCheng <bobwxc@email.cn>
> >
> > "_kernel_doc" label which should refer to the entire document was in the
> > middle, move it to top. Also fix zh translation.
> >
> > Fixes: 46347502b099 ("Restructure kernel-doc.rst")
> > Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
> > ---
> >  Documentation/doc-guide/kernel-doc.rst                    | 3 ++-
> >  Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 3 ++-
> >  2 files changed, 4 insertions(+), 2 deletions(-)
> 
> Rather than do this, is there any reason to not just delete the label
> entirely?  If anything references it, it can just name the file instead.
> But, as it happens, it's not even referenced anywhere...

Emmm, it's referenced. Remember to remove prefix '_' when grep.
Would you like to transfer all below references to path style?

$git grep -n "<kernel_doc>"
Documentation/process/submit-checklist.rst:64:11) Include :ref:`kernel-doc <kernel_doc>` to document global  kernel APIs.
Documentation/process/submit-checklist.rst:67:    :ref:`kernel-doc <kernel_doc>` and fix any issues.
Documentation/translations/it_IT/process/submit-checklist.rst:69:11) Includete commenti :ref:`kernel-doc <kernel_doc>` per documentare API
Documentation/translations/it_IT/process/submit-checklist.rst:71:    verificare i commenti :ref:`kernel-doc <kernel_doc>` ed eventualmente
Documentation/translations/zh_CN/process/submit-checklist.rst:59:11) 包括 :ref:`kernel-doc <kernel_doc>` 内核文档以记录全局内核API。（静态函数
Documentation/translations/zh_CN/process/submit-checklist.rst:61:    :ref:`kernel-doc <kernel_doc>` 并修复任何问题。
Documentation/translations/zh_TW/process/submit-checklist.rst:62:11) 包括 :ref:`kernel-doc <kernel_doc>` 內核文檔以記錄全局內核API。（靜態函數
Documentation/translations/zh_TW/process/submit-checklist.rst:64:    :ref:`kernel-doc <kernel_doc>` 並修復任何問題。

Thanks,

-- 
Wu XiangCheng	0x32684A40BCA7AEA7