Merge tag 'docs-6.5-2' of git://git.lwn.net/linux

torvalds · torvalds · commit 7210de3a328c · 2023-07-06T22:15:38.000-07:00
Pull mode documentation updates from Jonathan Corbet:
 "A half-dozen late arriving docs patches. They are mostly fixes, but we
  also have a kernel-doc tweak for enums and the long-overdue removal of
  the outdated and redundant patch-submission comments at the top of the
  MAINTAINERS file"

* tag 'docs-6.5-2' of git://git.lwn.net/linux:
  scripts: kernel-doc: support private / public marking for enums
  Documentation: KVM: SEV: add a missing backtick
  Documentation: ACPI: fix typo in ssdt-overlays.rst
  Fix documentation of panic_on_warn
  docs: remove the tips on how to submit patches from MAINTAINERS
  docs: fix typo in zh_TW and zh_CN translation
diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst
@@ -103,7 +103,7 @@ allows a persistent, OS independent way of storing the user defined SSDTs. There
 is also work underway to implement EFI support for loading user defined SSDTs
 and using this method will make it easier to convert to the EFI loading
 mechanism when that will arrive. To enable it, the
-CONFIG_EFI_CUSTOM_SSDT_OVERLAYS shoyld be chosen to y.
+CONFIG_EFI_CUSTOM_SSDT_OVERLAYS should be chosen to y.
 
 In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel
 command line parameter can be used (the name has a limitation of 16 characters).
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
@@ -4064,7 +4064,7 @@
 			extra details on the taint flags that users can pick
 			to compose the bitmask to assign to panic_on_taint.
 
-	panic_on_warn	panic() instead of WARN().  Useful to cause kdump
+	panic_on_warn=1	panic() instead of WARN().  Useful to cause kdump
 			on a WARN().
 
 	parkbd.port=	[HW] Parallel port number the keyboard adapter is
diff --git a/Documentation/process/6.Followthrough.rst b/Documentation/process/6.Followthrough.rst
@@ -51,6 +51,13 @@ mind:
    working toward the creation of the best kernel they can; they are not
    trying to create discomfort for their employers' competitors.
 
+ - Be prepared for seemingly silly requests for coding style changes
+   and requests to factor out some of your code to shared parts of
+   the kernel. One job the maintainers do is to keep things looking
+   the same. Sometimes this means that the clever hack in your driver
+   to get around a problem actually needs to become a generalized
+   kernel feature ready for next time.
+
 What all of this comes down to is that, when reviewers send you comments,
 you need to pay attention to the technical observations that they are
 making.  Do not let their form of expression or your own pride keep that
diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst
@@ -358,7 +358,7 @@ Andrew Morton 为有抱负的内核开发人员提供了如下建议
 	机器上始终完美运行”。通常的方法是和其他人一起解决问题（这可能需
 	要坚持！），但就是如此——这是内核开发的一部分。
 
-(http://lwn.net/articles/283982/)
+(http://lwn.net/Articles/283982/)
 
 在没有明显问题需要解决的情况下，通常建议开发人员查看当前的回归和开放缺陷
 列表。从来都不缺少需要解决的问题；通过解决这些问题，开发人员将从该过程获得
diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst
@@ -44,7 +44,7 @@
 	试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数
 	人的话。
 
-（http://lwn.net/articles/131776/）
+（http://lwn.net/Articles/131776/）
 
 实际情况却是不同的；与特定模块相比，内核开发人员更关心系统稳定性、长期维护
 以及找到问题的正确解决方案。这个故事的寓意是把重点放在问题上——而不是具体的
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -149,7 +149,7 @@ Linus对这个问题给出了最佳答案:
 	所以我们不会通过引入新问题来修复错误。这种方式是靠不住的，没人知道
 	是否真的有进展。是前进两步、后退一步，还是前进一步、后退两步？
 
-（http://lwn.net/articles/243460/）
+（http://lwn.net/Articles/243460/）
 
 特别不受欢迎的一种回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间，
 就必须无限期地支持它。这一事实使得用户空间接口的创建特别具有挑战性：因为它们
diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
@@ -98,7 +98,7 @@ Git提供了一些强大的工具，可以让您重写开发历史。一个不
    你可以给我发补丁，但当我从你那里拉取一个Git补丁时，我需要知道你清楚
    自己在做什么，我需要能够相信事情而 *无需* 手动检查每个单独的更改。
 
-（http://lwn.net/articles/224135/）。
+（http://lwn.net/Articles/224135/）。
 
 为了避免这种情况，请确保给定分支中的所有补丁都与相关主题紧密相关；“驱动程序
 修复”分支不应更改核心内存管理代码。而且，最重要的是，不要使用Git树来绕过
diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst
@@ -361,7 +361,7 @@ Andrew Morton 爲有抱負的內核開發人員提供了如下建議
 	機器上始終完美運行」。通常的方法是和其他人一起解決問題（這可能需
 	要堅持！），但就是如此——這是內核開發的一部分。
 
-(http://lwn.net/articles/283982/)
+(http://lwn.net/Articles/283982/)
 
 在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的回歸和開放缺陷
 列表。從來都不缺少需要解決的問題；通過解決這些問題，開發人員將從該過程獲得
diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst
@@ -47,7 +47,7 @@
 	試圖向這些人傳達用戶需求是浪費時間。他們太「聰明」了，根本聽不到少數
 	人的話。
 
-（http://lwn.net/articles/131776/）
+（http://lwn.net/Articles/131776/）
 
 實際情況卻是不同的；與特定模塊相比，內核開發人員更關心系統穩定性、長期維護
 以及找到問題的正確解決方案。這個故事的寓意是把重點放在問題上——而不是具體的
diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst
@@ -152,7 +152,7 @@ Linus對這個問題給出了最佳答案:
 	所以我們不會通過引入新問題來修復錯誤。這種方式是靠不住的，沒人知道
 	是否真的有進展。是前進兩步、後退一步，還是前進一步、後退兩步？
 
-（http://lwn.net/articles/243460/）
+（http://lwn.net/Articles/243460/）
 
 特別不受歡迎的一種回歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間，
 就必須無限期地支持它。這一事實使得用戶空間接口的創建特別具有挑戰性：因爲它們
diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst
@@ -101,7 +101,7 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不
    你可以給我發補丁，但當我從你那裡拉取一個Git補丁時，我需要知道你清楚
    自己在做什麼，我需要能夠相信事情而 *無需* 手動檢查每個單獨的更改。
 
-（http://lwn.net/articles/224135/）。
+（http://lwn.net/Articles/224135/）。
 
 爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；「驅動程序
 修復」分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過
diff --git a/Documentation/virt/kvm/x86/amd-memory-encryption.rst b/Documentation/virt/kvm/x86/amd-memory-encryption.rst
@@ -57,7 +57,7 @@ information, see the SEV Key Management spec [api-spec]_
 
 The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP.  If the argument
 to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled
-and ``ENOTTY` if it is disabled (on some older versions of Linux,
+and ``ENOTTY`` if it is disabled (on some older versions of Linux,
 the ioctl runs normally even with a NULL argument, and therefore will
 likely return ``EFAULT``).  If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP
 must be a struct kvm_sev_cmd::
diff --git a/MAINTAINERS b/MAINTAINERS
@@ -1,81 +1,5 @@
-List of maintainers and how to submit kernel changes
-====================================================
-
-Please try to follow the guidelines below.  This will make things
-easier on the maintainers.  Not all of these guidelines matter for every
-trivial patch so apply some common sense.
-
-Tips for patch submitters
--------------------------
-
-1.	Always *test* your changes, however small, on at least 4 or
-	5 people, preferably many more.
-
-2.	Try to release a few ALPHA test versions to the net. Announce
-	them onto the kernel channel and await results. This is especially
-	important for device drivers, because often that's the only way
-	you will find things like the fact version 3 firmware needs
-	a magic fix you didn't know about, or some clown changed the
-	chips on a board and not its name.  (Don't laugh!  Look at the
-	SMC etherpower for that.)
-
-3.	Make sure your changes compile correctly in multiple
-	configurations. In particular check that changes work both as a
-	module and built into the kernel.
-
-4.	When you are happy with a change make it generally available for
-	testing and await feedback.
-
-5.	Make a patch available to the relevant maintainer in the list. Use
-	``diff -u`` to make the patch easy to merge. Be prepared to get your
-	changes sent back with seemingly silly requests about formatting
-	and variable names.  These aren't as silly as they seem. One
-	job the maintainers (and especially Linus) do is to keep things
-	looking the same. Sometimes this means that the clever hack in
-	your driver to get around a problem actually needs to become a
-	generalized kernel feature ready for next time.
-
-	PLEASE check your patch with the automated style checker
-	(scripts/checkpatch.pl) to catch trivial style violations.
-	See Documentation/process/coding-style.rst for guidance here.
-
-	PLEASE CC: the maintainers and mailing lists that are generated
-	by ``scripts/get_maintainer.pl.`` The results returned by the
-	script will be best if you have git installed and are making
-	your changes in a branch derived from Linus' latest git tree.
-	See Documentation/process/submitting-patches.rst for details.
-
-	PLEASE try to include any credit lines you want added with the
-	patch. It avoids people being missed off by mistake and makes
-	it easier to know who wants adding and who doesn't.
-
-	PLEASE document known bugs. If it doesn't work for everything
-	or does something very odd once a month document it.
-
-	PLEASE remember that submissions must be made under the terms
-	of the Linux Foundation certificate of contribution and should
-	include a Signed-off-by: line.  The current version of this
-	"Developer's Certificate of Origin" (DCO) is listed in the file
-	Documentation/process/submitting-patches.rst.
-
-6.	Make sure you have the right to send any changes you make. If you
-	do changes at work you may find your employer owns the patch
-	not you.
-
-7.	When sending security related changes or reports to a maintainer
-	please Cc: security@kernel.org, especially if the maintainer
-	does not respond. Please keep in mind that the security team is
-	a small set of people who can be efficient only when working on
-	verified bugs. Please only Cc: this list when you have identified
-	that the bug would present a short-term risk to other users if it
-	were publicly disclosed. For example, reports of address leaks do
-	not represent an immediate threat and are better handled publicly,
-	and ideally, should come with a patch proposal. Please do not send
-	automated reports to this list either. Such bugs will be handled
-	better and faster in the usual public places. See
-	Documentation/process/security-bugs.rst for details.
-
-8.	Happy hacking.
+List of maintainers
+===================
 
 Descriptions of section entries and preferred order
 ---------------------------------------------------
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
@@ -1319,6 +1319,9 @@ sub dump_enum($$) {
     my $file = shift;
     my $members;
 
+    # ignore members marked private:
+    $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+    $x =~ s/\/\*\s*private:.*}/}/gosi;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     # strip #define macros inside enums
diff --git a/tools/testing/selftests/rcutorture/bin/kvm.sh b/tools/testing/selftests/rcutorture/bin/kvm.sh
@@ -655,4 +655,4 @@ fi
 # Control buffer size: --bootargs trace_buf_size=3k
 # Get trace-buffer dumps on all oopses: --bootargs ftrace_dump_on_oops
 # Ditto, but dump only the oopsing CPU: --bootargs ftrace_dump_on_oops=orig_cpu
-# Heavy-handed way to also dump on warnings: --bootargs panic_on_warn
+# Heavy-handed way to also dump on warnings: --bootargs panic_on_warn=1
