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

[Lorenzo Stoakes <lorenzo.stoakes@oracle.com>]

On Tue, Jun 03, 2025 at 08:01:02AM -0600, Jonathan Corbet wrote:
> Lorenzo Stoakes <lorenzo.stoakes@oracle.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