linux-kernel - Re: [PATCH 1/4] Docs: usb: update usb_bulk

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Fri, 3 Dec 2021 11:01:49 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Alan Stern <stern@...land.harvard.edu>,
        Philipp Hortmann <philipp.g.hortmann@...il.com>
Cc:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-usb@...r.kernel.org
Subject: Re: [PATCH 1/4] Docs: usb: update usb_bulk_msg receiving example

Hi,

On Thu, 2 Dec 2021 14:49:08 -0500, Alan Stern wrote:
> On Thu, Dec 02, 2021 at 05:49:47AM +0100, Philipp Hortmann wrote:
[...]
>> Please find the full email under the link:
>> https://lore.kernel.org/linux-usb/87h7dcsohs.fsf@meer.lwn.net/T/
>> 
>> Please give me an example for the right wording. I am not a native English
>> speaker. Is the article in this case required?
> 
> Okay, now I see what's going on.  You should change it like this:
> 
> -driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
> +driver. Instead we call `usb_bulk_msg`, which can be used
>  to send or receive data from a device without having to create urbs and
> -handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
> +handle urb completion callback functions. We call `usb_bulk_msg`,
>  giving it a buffer into which to place any data received from

Well, for function names to be caught by kernel-doc tools,
you need to say usb_bulk_msg() (without ``, with () appended).

So, the diff should look:

-driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
+driver. Instead we call usb_bulk_msg(), which can be used
 to send or receive data from a device without having to create urbs and
-handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
+handle urb completion callback functions. We call usb_bulk_msg(),
 giving it a buffer into which to place any data received from

You can find related documentation at:

   https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext

        Thanks, Akira

> 
> Alan Stern