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: <87y0u87v3g.fsf@trenco.lwn.net>
Date: Tue, 03 Jun 2025 08:33:55 -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:

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

Who said anything about it being a requirement?  I think we have gone
way off track here.

Certainly it would be *nice* to have all of that stuff documented, and I
think there is value in giving a visual clue for stuff that lacks
documentation, but I never said anything about requirements.

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

Because you're thinking in terms of the rendered docs, and not the
people who read the plain text.  "function()" is far more readable than
":c:func:`!function()`", don't you agree?  And rather easier to write as
well.

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

The cross-referencing is *to* the API documentation.  Again, you are
mentioning a function, why would you *not* want to let the system
automatically link to that function's documentation?  Especially since
you're using markup that is explicitly provided for exactly that
purpose?  Does the link cause some sort of harm?

Thanks,

jon