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 09:05:32AM -0600, Jonathan Corbet wrote:
> Lorenzo Stoakes <lorenzo.stoakes@oracle.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...

Yeah I will do so...

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

...with this hack as needed :)

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

OK thanks for clarifying, so let's do a take 2 of the action items:

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.

3. I will create a follow-up series to address these issues in this file
   -in general-.

4. Drop '!' from every reference so we get automated cross-referencing (with the
   ** struct ** hack as needed).

5. Where possible see if we have functions documented, and if so avoid the
   :c:... noise. If we can't avoid it for now, note down the functions and add
   to todo to get documented. We can remove the gunk as we go...

A couple questions on point 5:

- When you say 'documentation', do you mean the /** kernel-doc stuff?

- Does running `make SPHINXDIRS=mm htmldocs` suffice to have this script run? As
  this is how I've been previewing my changes so far!

Thanks,

Lorenzo