On Tue, Jun 03, 2025 at 08:08:22AM -0600, Jonathan Corbet wrote: > Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> writes: > > > On Mon, Jun 02, 2025 at 03:38:55PM -0600, Jonathan Corbet wrote: > >> Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> 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
