linux-kernel - [PATCH 0/2] kernel-doc and MAINTAINERS clean-up

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20210322122542.15072-1-lukas.bulwahn@gmail.com>
Date:   Mon, 22 Mar 2021 13:25:40 +0100
From:   Lukas Bulwahn <lukas.bulwahn@...il.com>
To:     Andrew Morton <akpm@...ux-foundation.org>, linux-mm@...ck.org
Cc:     Joe Perches <joe@...ches.com>,
        Ralf Ramsauer <ralf.ramsauer@...-regensburg.de>,
        linux-doc@...r.kernel.org, kernel-janitors@...r.kernel.org,
        linux-kernel@...r.kernel.org,
        Lukas Bulwahn <lukas.bulwahn@...il.com>
Subject: [PATCH 0/2] kernel-doc and MAINTAINERS clean-up

Roughly 900 warnings of about 21.000 kernel-doc warnings in the kernel tree
warn with 'cannot understand function prototype:', i.e., the kernel-doc parser
cannot parse the function's signature. The majority, about 600 cases of those,
are just struct definitions following the kernel-doc description. Further,
spot-check investigations suggest that the authors of the specific kernel-doc
descriptions simply were not aware that the general format for a kernel-doc
description for a structure requires to prefix the struct name with the keyword
'struct', as in 'struct struct_name - Brief description.'. Details on
kernel-doc are at the Link below.

Without the struct keyword, kernel-doc does not check if the kernel-doc
description fits to the actual struct definition in the source code.
Fortunately, in roughly a quarter of these cases, the kernel-doc description is
actually complete wrt. its corresponding struct definition. So, the trivial
change adding the struct keyword will allow us to keep the kernel-doc
descriptions more consistent for future changes, by checking for new kernel-doc
warnings.

Also, some of the files in ./include/ are not assigned to a specific
MAINTAINERS section and hence have no dedicated maintainer. So, if needed, the
files in ./include/ are also assigned to the fitting MAINTAINERS section, as I
need to identify whom to send the clean-up patch anyway.

Here is the change from this kernel-doc janitorial work in the ./include/
directory for MEMORY MANAGEMENT.

Andrew, please pick this clean-up patch series for mm.

Link: https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html

Lukas Bulwahn (2):
  MAINTAINERS: assign pagewalk.h to MEMORY MANAGEMENT
  pagewalk: prefix struct kernel-doc descriptions

 MAINTAINERS              | 1 +
 include/linux/pagewalk.h | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

-- 
2.17.1