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:08:22AM -0600, Jonathan Corbet wrote:
> Lorenzo Stoakes <lorenzo.stoakes@oracle.com> writes:
>
> > On Mon, Jun 02, 2025 at 03:38:55PM -0600, Jonathan Corbet wrote:
> >> Lorenzo Stoakes <lorenzo.stoakes@oracle.com> writes:
> >>
> >> > --- a/Documentation/mm/process_addrs.rst
> >> > +++ b/Documentation/mm/process_addrs.rst
> >> > @@ -303,7 +303,9 @@ There are four key operations typically performed on page tables:
> >> >  1. **Traversing** page tables - Simply reading page tables in order to traverse
> >> >     them. This only requires that the VMA is kept stable, so a lock which
> >> >     establishes this suffices for traversal (there are also lockless variants
> >> > -   which eliminate even this requirement, such as :c:func:`!gup_fast`).
> >> > +   which eliminate even this requirement, such as :c:func:`!gup_fast`). There is
> >> > +   also a special case of page table traversal for non-VMA regions which we
> >>
> >> The "!gup_fast" caught my attention - I was unaware that Sphinx had such
> >> a thing.  Its purpose would be to appear to suppress the generation of the
> >> link that turns the cross reference into a cross reference.
> >>
> >> The MM docs are full of these, do we know why?
> >
> > Removing it from the struct vm_area_struct struct immediately give:
> >
> > /home/lorenzo/kerndev/kernels/mm/Documentation/mm/process_addrs.rst:11: WARNING: Unparseable C cross-reference: 'struct vm_area_struct'
> > Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
> >   struct vm_area_struct
> >
> > And given C's weirdness with typing I really prefer to be explicit in
> > referencing a struct vs. e.g. a typedef.
>
> That's because the :c:struct: markup doesn't want the word "struct" in
> there.  In this case, the "!" is being used, essentially, to hide the
> fact that the Sphinx markup is being entirely misused here.  You would
> be far better off just saying:
>
>   **struct vm_area_struct**
>
> and avoiding the uglier markup in this case.

I can go change that.

But to repeat - 'given C's weirdness with typing I really prefer to be
explicit in referencing a struct vs. e.g. a typedef.'

I'm not doing this with an intent of Sphix misuse, it's with intent of
being as clear as possible.

>
> Once again, taking out the markup entirely will cause the automarkup
> code to do the right thing, with the proviso that undocumented
> structures (which, tragically, includes struct vm_area_struct) won't be
> marked up in the current implementation.  By far the best solution here
> is to remove all of the markup and add a kerneldoc comment for this
> rather important structure.
>
> > At any rate I'm not sure it's all that useful to cross-reference these?
>
> 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!

>
> Thanks,
>
> jon