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: <877c1s9b6p.fsf@trenco.lwn.net>
Date: Tue, 03 Jun 2025 08:01:02 -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:

>> 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.

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

jon