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: <87ldq87tmr.fsf@trenco.lwn.net>
Date: Tue, 03 Jun 2025 09:05:32 -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:

> Thanks, I appreciate that. So I want to address your concerns as well as I
> can. I think I have misunderstood you a little bit here too (text is a poor
> medium, yada yada) so let me try to nail down what I feel is the sensible
> way forward:
>
> 1. Once I am confident I have correctly addressed Jann's feedback I'll
>    respin a v2 with the various 'sins' in place for the time being.
>
> 2. I will also drop the 'since v6.14' stuff you rightly raised in this
> respin.

So far so good

> 3. I will create a follow-up series to address these issues in this file
> -in general-:
>
> - Drop '!' from every reference so we get automated cross-referencing - I
>   think now I understand the point (hopefully!) that Sphinx with
>   automagically link every unique reference to a function/struct/etc. to
>   one another.

If you just drop the "!" you'll run into the "struct" problem you
mentioned before.  You'll need to take out "struct" as well if you go
this route...

> - Perhaps hack in a **struct ** prefix so we get the 'best of both worlds'
>   on this for types...?

...so yes you'd need to do that.

> I think my misapprehension about defining functions was not realising that
> by doing :c:func:etc without the ! would automatically provide that
> definition upon first reference to that function/struct/etc.?
>
> Is that correct/sensible?
>
> Would you want me to only use the :c:func: stuff in the _first_ mention of
> a function and then to not use it from then on?
>
> I wonder if the _appropriate_ use of :c:func:...: is in the actual
> definition, but since it's not really practical to do that right now* is
> simply doing it upon first mention a sensible 'least worst' approach here?

Here, I think, we've gone a bit off track again.  The goal of the
automarkup code was to *never* need to use the :c:func: markup.  Let's
just say that ... certain members of our community ... found that markup
entirely intolerable - and, in truth, it is ugly.  So I wrote the
initial automarkup extension; now, any time that the docs build sees
function(), it looks for documentation for that function and creates a
cross-reference if that documentation is found.

The goal is that you should never need the :c:gunk: ever.

Thanks,

jon