linux-kernel - Re: [PATCH] x86/sgx: Fix typos and formatting in function 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: <d390d171e858722850aecae0af68c30b9eb0e134.camel@intel.com>
Date: Tue, 4 Nov 2025 21:01:34 +0000
From: "Huang, Kai" <kai.huang@...el.com>
To: "thorsten.blum@...ux.dev" <thorsten.blum@...ux.dev>
CC: "jarkko@...nel.org" <jarkko@...nel.org>, "x86@...nel.org"
	<x86@...nel.org>, "bp@...en8.de" <bp@...en8.de>, "linux-sgx@...r.kernel.org"
	<linux-sgx@...r.kernel.org>, "hpa@...or.com" <hpa@...or.com>,
	"mingo@...hat.com" <mingo@...hat.com>, "tglx@...utronix.de"
	<tglx@...utronix.de>, "dave.hansen@...ux.intel.com"
	<dave.hansen@...ux.intel.com>, "linux-kernel@...r.kernel.org"
	<linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] x86/sgx: Fix typos and formatting in function comments

On Tue, 2025-11-04 at 20:13 +0100, Thorsten Blum wrote:
> On 4. Nov 2025, at 00:47, Huang, Kai wrote:
> > It seems we don't have a consistent way of describing return values in the
> > k-doc comments in sgx/main.c.  E.g.,
> > 
> > /**
> > * sgx_unmark_page_reclaimable() - Remove a page from the reclaim list
> > 
> > ...
> > 
> > * Return:
> > *   0 on success,
> > *   -EBUSY if the page is in the process of being reclaimed
> > */
> > 
> > 
> > /**
> > * sgx_alloc_epc_page() - Allocate an EPC page
> > 
> > ...
> > 
> > * Return:
> > *   an EPC page,
> > *   -errno on error
> > */
> > 
> > Perhaps we should make them consistent in format.
> > 
> > But I think this can be done separately from fixing the typos.  Maybe you 
> > can split out the typo fixing as a separate patch, and have another patch to
> > fixing the return value description?
> 
> I used the style mostly found in main.c and ioctl.c - would that be the
> "correct" format for the others as well? Happy to submit a separate
> patch if it's worth it.

I found a link documenting that (please search "Return values"):

https://docs.kernel.org/doc-guide/kernel-doc.html

In short, the doc suggested to use a "ReST list", e.g.,:

	* Return:
	* * %0            - OK to runtime suspend the device
	* * %-EBUSY       - Device should not be runtime suspended

But I am not a fan of cleaning up all the existing SGX comments to it, since
this will just be a burden to maintainers I suppose.  And I bet there are
other places in the kernel not following this "ReST list", i.e., I view this
as a suggestion but not a requirement.

Another option is you can just change to follow the quoted two examples
above (e.g., sgx_unmark_page_reclaimable()) so that at least in sgx/main.c
they are consistent.

Or just leave the comment as is.

That's my 2cents, and in any way, I will be happy to review.