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:

> 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.
It's hard enough to get documentation written as it is, I certainly
don't want to make it harder.

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