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

[Jonathan Corbet <corbet@lwn.net>]

Lorenzo Stoakes <lorenzo.stoakes@oracle.com> writes:

>> Re: the c:func: stuff -
>>
>> Well, the right thing is making function + type names clearly discernable, and
>> it just putting in the function name like that absolutely does not do the right
>> thing in that respect.
>>
>> I feel strongly on this, as I've tried it both ways and it's a _really_ big
>> difference in how readable the document is.
>>
>> I spent a lot of time trying to make it as readable as possible (given the
>> complexity) so would really rather not do anything that would hurt that.
>>
>
> Somebody told me that in _other_ .rst's, seemingly, it does figure out xxx() ->
> function and highlights it like this.
>
> But for me, it does not... :)

OK ... If you look at what's going on, some of the functions will be
marked, others not.  The difference is that there is no markup for
functions where a cross-reference cannot be made (because they are
undocumented).

We could easily change the automarkup code to always do the markup; the
problem with that (which is also a problem with the existing markup
under Documentation/mm) is you'll have rendered text that looks like a
cross-reference link, but which is not.  We also lose a clue as to which
functions are still in need of documentation.

The right answer might be to mark them up differently, I guess.

jon