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

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

Let me reply in one place as we're currently having 2 largely similar
conversations in parallel which is unhelpful... :)

On Tue, Jun 03, 2025 at 08:37:23AM -0600, Jonathan Corbet wrote:
> Lorenzo Stoakes <lorenzo.stoakes@oracle.com> writes:
>
> > But to repeat - 'given C's weirdness with typing I really prefer to be
> > explicit in referencing a struct vs. e.g. a typedef.'
>
> ...and I think that makes perfect sense.
>
> >> Why would you *not* want to cross-reference something and make life easier
> >> for your reader?
> >
> > Because it apparently requires me to document every function I reference?
> > Unless I'm missing something?
> >
> > I may be misunderstanding you.
> >
> > If not then fine, I can delay this patch, go off and do a 'cleanup' patch
> > first, that will drop the '!'s and come back to this.
> >
> > But if I need to document every referenced function that just isn't
> > feasible for me with my current workload.
> >
> > Please clarify!
>
> Hopefully I already have - I'm in no position to enforce such a
> requirement, even if I thought it would be a good thing -- and I don't.

I think Andrew would think otherwise :)

Everybody respects you a great deal, myself included, so your opinion
counts for a LOT.

> It's hard enough to get documentation written as it is, I certainly
> don't want to make it harder.

Yeah, I mean I take your points and it's important to me to make sure I've
done this as well as I can, but this is my main concern here. Often times
this stuff feels rather thankless... so we must maintain a balance here I
feel.

Anyway, I think we can figure out a good solution here that should
hopefully be satisfactory for all (see below...)

>
> My suggestion would be: proceed with your changes for now, it was never
> my purpose to put obstacles there.  I'll look at having automarkup do
> something a bit more useful for references that lack documentation, then
> maybe I'll do a cleanup pass on some of the mm docs if nobody else gets
> there first.
>
> Thanks,
>
> jon

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.

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.

- Perhaps hack in a **struct ** prefix so we get the 'best of both worlds'
  on this for types...?

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?

Let me know what makes sense!

Thanks,

Lorenzo

*I could add to my TODO to ensure we have at least kerneldoc descriptions
 for every referenced function, and gradually burn these down as I add
 them, I just can't guarantee you this will happen any time soon :)