linux-kernel - Re: [PATCH] docs/mm: expand vma doc to highlight pte freeing, non-vma traversal

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: <87tt4w7uxo.fsf@trenco.lwn.net>
Date: Tue, 03 Jun 2025 08:37:23 -0600
From: Jonathan Corbet <corbet@....net>
To: Lorenzo Stoakes <lorenzo.stoakes@...cle.com>
Cc: Andrew Morton <akpm@...ux-foundation.org>, Suren Baghdasaryan
 <surenb@...gle.com>, "Liam R . Howlett" <Liam.Howlett@...cle.com>,
 Vlastimil Babka <vbabka@...e.cz>, Shakeel Butt <shakeel.butt@...ux.dev>,
 Jann Horn <jannh@...gle.com>, Qi Zheng <zhengqi.arch@...edance.com>,
 linux-mm@...ck.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs/mm: expand vma doc to highlight pte freeing,
 non-vma traversal

Lorenzo Stoakes <lorenzo.stoakes@...cle.com> writes:

> But to repeat - 'given C's weirdness with typing I really prefer to be
> explicit in referencing a struct vs. e.g. a typedef.'

...and I think that makes perfect sense.

>> Why would you *not* want to cross-reference something and make life easier
>> for your reader?
>
> Because it apparently requires me to document every function I reference?
> Unless I'm missing something?
>
> I may be misunderstanding you.
>
> If not then fine, I can delay this patch, go off and do a 'cleanup' patch
> first, that will drop the '!'s and come back to this.
>
> But if I need to document every referenced function that just isn't
> feasible for me with my current workload.
>
> Please clarify!

Hopefully I already have - I'm in no position to enforce such a
requirement, even if I thought it would be a good thing -- and I don't.
It's hard enough to get documentation written as it is, I certainly
don't want to make it harder.

My suggestion would be: proceed with your changes for now, it was never
my purpose to put obstacles there.  I'll look at having automarkup do
something a bit more useful for references that lack documentation, then
maybe I'll do a cleanup pass on some of the mm docs if nobody else gets
there first.

Thanks,

jon