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: <28f53f7e-5ac2-4ef4-8944-6741161e6870@lucifer.local>
Date: Tue, 3 Jun 2025 15:11:24 +0100
From: Lorenzo Stoakes <lorenzo.stoakes@...cle.com>
To: Jonathan Corbet <corbet@....net>
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

On Tue, Jun 03, 2025 at 08:01:02AM -0600, Jonathan Corbet wrote:
> Lorenzo Stoakes <lorenzo.stoakes@...cle.com> writes:
>
> >> Re: the c:func: stuff -
> >>
> >> Well, the right thing is making function + type names clearly discernable, and
> >> it just putting in the function name like that absolutely does not do the right
> >> thing in that respect.
> >>
> >> I feel strongly on this, as I've tried it both ways and it's a _really_ big
> >> difference in how readable the document is.
> >>
> >> I spent a lot of time trying to make it as readable as possible (given the
> >> complexity) so would really rather not do anything that would hurt that.
> >>
> >
> > Somebody told me that in _other_ .rst's, seemingly, it does figure out xxx() ->
> > function and highlights it like this.
> >
> > But for me, it does not... :)
>
> OK ... If you look at what's going on, some of the functions will be
> marked, others not.  The difference is that there is no markup for
> functions where a cross-reference cannot be made (because they are
> undocumented).
>
> We could easily change the automarkup code to always do the markup; the
> problem with that (which is also a problem with the existing markup
> under Documentation/mm) is you'll have rendered text that looks like a
> cross-reference link, but which is not.  We also lose a clue as to which
> functions are still in need of documentation.

Isn't it a pretty egregious requirement to require documentation of every
referenced function?

I mean if that were a known requirement I'd simply not have written this
document at all, frankly.

And it's one I feel is really quite important, since this behaviour is
complicated, confusing and has led to bugs, including security flaws.

I really think we have to be careful about having barriers in the way of
people writing documentation as much as possible.

>
> The right answer might be to mark them up differently, I guess.

But... what I'm doing here, and what mm does elsewhere works perfectly fine? Why
do we need something new?

Surely this cross-referencing stuff is more useful for API documentation
that explicitly intends to describe functions like this?

>
> jon