Re: [PATCH 1/4] Docs: usb: update usb_bulk_msg receiving example

[Akira Yokosawa]

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@xxxxxxxxxxxx/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