linux-kernel - Re: [PATCH 1/2] power/swap: add missing params and Return: descriptions to kernel-doc comments

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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <CAJZ5v0jga6AtyWnAgKhcKYFJagEf+ZQmnm5y92zaPXGAkXHQZg@mail.gmail.com>
Date: Fri, 7 Nov 2025 21:19:02 +0100
From: "Rafael J. Wysocki" <rafael@...nel.org>
To: Sunday Adelodun <adelodunolaoluwa@...oo.com>
Cc: "Rafael J. Wysocki" <rafael@...nel.org>, lenb@...nel.org, pavel@...nel.org, 
	anna-maria@...utronix.de, frederic@...nel.org, mingo@...nel.org, 
	tglx@...utronix.de, linux-pm@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 1/2] power/swap: add missing params and Return:
 descriptions to kernel-doc comments

On Fri, Nov 7, 2025 at 9:09 PM Sunday Adelodun
<adelodunolaoluwa@...oo.com> wrote:
>
> On 11/7/25 16:36, Rafael J. Wysocki wrote:
> > On Thu, Nov 6, 2025 at 12:40 PM Sunday Adelodun
> > <adelodunolaoluwa@...oo.com> wrote:
> >> Kernel-doc checks (scripts/kernel-doc) reported a number of warnings
> >> for missing parameters and `Return:` descriptions in kernel/power/swap.c.
> >> These missing return descriptions make the generated documentation
> >> noisy and break doc-build when -Werror is used.
> >>
> >> Update the kernel-doc comment blocks to add explicit
> >> Return: lines (and a few parameter tags where helpful) for the functions
> >> that were triggering warnings. No functional code changes are made.
> >>
> >> Example warnings that motivated this change:
> >>   - Warning: kernel/power/swap.c:535 No description found for return value
> >>     of 'save_image'
> >>   - Warning: kernel/power/swap.c:687 No description found for return value
> >>    of 'save_compressed_image'
> >>   - Warning: kernel/power/swap.c:941 No description found for return value
> >>     of 'swsusp_write'
> >>
> >> Signed-off-by: Sunday Adelodun <adelodunolaoluwa@...oo.com>
> > These comments need more changes to become proper kerneldocs and in
> > some cases it is not even necessary because the functions in question
> > are static.
> >
> > If the goal is to avoid warnings, why don't you change them all to
> > non-kerneldoc regular comments?
>
> Thank you very much for the feedback.
>
> For the functions that are not static, could you please suggest the
> appropriate changes needed to make their comments proper? I would like
> to improve them accordingly.

There are some white space changes to be made and general formatting
needs to be improved in some cases.

> My initial goal was to address the warnings, but if converting them to
> regular comments
>
> is the preferred approach, I will go ahead and update them that way in v2.

I would split this into 2 patches, one changing the comments on the
static functions to non-kerneldoc (and maybe dropping some of them
entirely) and the other changing the remaining comments into proper
kerneldoc ones.

Thanks!