Re: [PATCH] docs: core-api: include documentation from linux/uaccess.h

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] docs: core-api: kernel-doc and Sphinx warnings from linux/uaccess.h
--

commit 2999ceef858b0ddc1bc84f5c20261a45d3fb5ade
Author: Jonathan Corbet <corbet@lwn.net>

docs: core-api: include documentation from linux/uaccess.h

This commit adds a kernel-doc directive to Documentation/core-api/mm-api.rst
to include internal kernel-doc comments from include/linux/uaccess.h.

> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index c1d03a5a2a192..b8c00bc5314e1 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -8,6 +8,9 @@ User Space Memory Access
>  .. kernel-doc:: arch/x86/include/asm/uaccess.h
>     :internal:
>  
> +.. kernel-doc:: include/linux/uaccess.h
> +   :internal:
> +
>  .. kernel-doc:: arch/x86/lib/usercopy_32.c
>     :export:
>  

[Severity: Low]
Does pulling include/linux/uaccess.h into the documentation build introduce
kernel-doc and Sphinx warnings during make htmldocs?

First, in include/linux/uaccess.h, the comments above
copy_struct_from_bounce_buffer() and copy_struct_to_bounce_buffer() start
with /** without a kernel-doc identifier line:

    /**
     * This is like copy_struct_from_user(), but the
     * src buffer was already copied into a kernel
     * bounce buffer, so it will never return -EFAULT.
     */
    static __always_inline __must_check int
    copy_struct_from_bounce_buffer(void *dst, size_t dstsize,
                                   const void *src, size_t srcsize)

When KernelDoc.process_name() in tools/lib/python/kdoc/kdoc_parser.py parses
these comments, it emits a warning that the comment starts with /** but is
not a valid kernel-doc comment, and omits both functions from the generated
output.

Second, the kernel-doc comments for copy_struct_from_user(),
copy_struct_to_user(), and __scoped_user_access() in include/linux/uaccess.h
include indented C code examples preceded by : or . rather than a :: literal
block marker:

     * @ksize is just sizeof(*dst), and @usize should've been passed by userspace.
     * The recommended usage is something like the following:
     *
     *   SYSCALL_DEFINE2(foobar, const struct foo __user *, uarg, size_t, usize)
     *   {
     *      int err;
     *      struct foo karg = {};

and in __scoped_user_access():

     * wrapped. See unsafe_get_user() for reference.
     *
     *	scoped_user_rw_access(ptr, efault) {
     *		unsafe_get_user(rval, &ptr->rval, efault);
     *		unsafe_put_user(wval, &ptr->wval, efault);
     *	}
     *	return 0;
     *  efault:
     *	return -EFAULT;

Without ::, RestFormat.output_highlight() in
tools/lib/python/kdoc/kdoc_output.py does not treat these blocks as literal
code, causing Sphinx to emit unexpected unindent warnings on the closing
braces and the efault: label, as well as inline emphasis warnings on the
unescaped pointer asterisks in sizeof(*dst), sizeof(*src), and
struct foo __user *.

Finally, in __scoped_user_access(), scoped_user_read_access(),
scoped_user_write_access(), and scoped_user_rw_access() in
include/linux/uaccess.h, parameter references sit directly adjacent to
token-pasting or dereference operators:

     * When the scope is left user_##@_mode##_access_end() is automatically

and:

     * The size of the access starting from @usrc is determined via sizeof(*@usrc)).

RestFormat expands @param into **param**, turning these into
user_##**_mode**##_access_end() and sizeof(***usrc**)) (along with *@udst and
*@uptr), which triggers further Sphinx inline strong/emphasis markup
warnings. Should the comments in include/linux/uaccess.h be cleaned up before
including the header in Documentation/core-api/mm-api.rst?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/878q3q4qby.fsf@trenco.lwn.net?part=1