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

[Jonathan Corbet]

Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> 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...

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

> 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