linux-kernel - Re: linux-next: build warning after merge of the xfs tree

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <22187737-e0ad-4cc4-98fd-5e43ebc5ecee@gmail.com>
Date: Sat, 24 Feb 2024 18:07:28 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: hch@....de
Cc: chandanbabu@...nel.org, corbet@....net, david@...morbit.com,
 djwong@...nel.org, linux-kernel@...r.kernel.org, linux-next@...r.kernel.org,
 linux-xfs@...r.kernel.org, mchehab@...nel.org, sfr@...b.auug.org.au,
 Akira Yokosawa <akiyks@...il.com>
Subject: Re: linux-next: build warning after merge of the xfs tree

Hi,

On Fri, 23 Feb 2024 15:06:19 +0100, Christoph Hellwig wrote:
> On Fri, Feb 23, 2024 at 09:55:09AM +0100, Mauro Carvalho Chehab wrote:
>> but it is very weird for the ones reading the text file. So, what
>> we do instead for pointers is to escape the entire declaration, like:
>> 
>> 	``*inode``
>> 	``struct inode *inode``
>> 
>> I hope that helps.
> 
> In this case it says *foliop for an argument that is a double pointer
> and the comment refers to what it point to.  I'll see what I can do
> there, but the whole italic and bold thing seems entirely pointless
> for kerneldoc..

Indeed.

How about teaching kernel-doc unary "*" on param?

Substitution would look like:

   (kernel-doc)       (RST)
   *@...am     ->  ***param**

Sphinx detects double asterisk, starts strong emphasis, waits for
another double asterisk to appear, and stops strong emphasis.
Hence you would get boldface "*param" in pretty printed docs.

Diff below (against docs-next) should add a rule for param_deref
(only for RST).

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 136104804375..bdd6f3b489cc 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -65,7 +65,7 @@ my $type_constant = '\b``([^\`]+)``\b';
 my $type_constant2 = '\%([-_\*\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
-my $type_param_ref = '([\!~]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
+my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
 my $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
 my $type_env = '(\$\w+)';
-- 

And you would be able to write the kernel-doc comment in question
as follows:

diff --git a/mm/shmem.c b/mm/shmem.c
index 750ab1dcae27..0aad0d9a621b 100644
--- a/mm/shmem.c
+++ b/mm/shmem.c
@@ -2152,8 +2152,8 @@ static int shmem_get_folio_gfp(struct inode *inode, pgoff_t index,
  * There is no need to reserve space before calling folio_mark_dirty().
  *
  * When no folio is found, the behavior depends on @sgp:
- *  - for SGP_READ, *foliop is %NULL and 0 is returned
- *  - for SGP_NOALLOC, *foliop is %NULL and -ENOENT is returned
+ *  - for SGP_READ, *@...iop is %NULL and 0 is returned
+ *  - for SGP_NOALLOC, *@...iop is %NULL and -ENOENT is returned
  *  - for all other flags a new folio is allocated, inserted into the
  *    page cache and returned locked in @foliop.
  *
-- 

How does this approach sound to you? 

        Thanks, Akira