[PATCH v2 26/28] docs: kernel-doc.rst: document private: scope propagation

Mauro Carvalho Chehab
2026-03-12T14:55:02Z

This was an undefined behavior, but at least one place used private:
inside a nested struct meant to not be propagated outside it.

Kernel-doc now defines how this is propagated. So, document that.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/doc-guide/kernel-doc.rst | 6 ++++++
1 file changed, 6 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 8d2c09fb36e4..1c148fe8e1f9 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -213,6 +213,10 @@ The ``private:`` and ``public:`` tags must begin immediately following a
``/*`` comment marker. They may optionally include comments between the
``:`` and the ending ``*/`` marker.

+When ``private:`` is used on nested structs, it propagates only to inner
+structs/unions.
+
+
Example::

/**
@@ -256,8 +260,10 @@ It is possible to document nested structs and unions, like::
union {
struct {
int memb1;
+ /* private: hides memb2 from documentation */
int memb2;
};
+ /* Everything here is public again, as private scope finished */
struct {
void *memb3;
int memb4;
--
2.52.0