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

[Alan Stern]

On Thu, Dec 02, 2021 at 05:49:47AM +0100, Philipp Hortmann wrote:
> On 11/30/21 9:10 PM, Alan Stern wrote:
> > On Mon, Nov 29, 2021 at 09:21:41PM +0100, Philipp Hortmann wrote:
> > > Clarification that this example is not in the driver template anymore.
> > > Update code example so that it fits best to usb-skeleton.c
> > > 
> > > Signed-off-by: Philipp Hortmann <philipp.g.hortmann@xxxxxxxxx>
> > > ---
> > >   .../driver-api/usb/writing_usb_driver.rst     | 30 +++++++++----------
> > >   1 file changed, 15 insertions(+), 15 deletions(-)
> > > 
> > > diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst
> > > index b43e1ce49f0e..a9608ad18d77 100644
> > > --- a/Documentation/driver-api/usb/writing_usb_driver.rst
> > > +++ b/Documentation/driver-api/usb/writing_usb_driver.rst
> > > @@ -218,36 +218,36 @@ do very much processing at that time. Our implementation of
> > >   ``skel_write_bulk_callback`` merely reports if the urb was completed
> > >   successfully or not and then returns.
> > > -The read function works a bit differently from the write function in
> > > +This read function works a bit differently from the write function in
> > >   that we do not use an urb to transfer data from the device to the
> > > -driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
> > > +driver. Instead we call `usb_bulk_msg` function, 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`
> > >   function, giving it a buffer into which to place any data received from
> > 
> > The reason for the last two changes above isn't clear.  You removed some of the
> > markup indicators and made the text ungrammatical.  This does not seem like an
> > improvement.
> > 
> > Alan Stern
> > 
> This two changes were made because of an earlier comment to the same
> document, but may be I understood this wrong:
> On 10/19/21 11:17 PM, Jonathan Corbet wrote:
> ...
> We shouldn't be using :c:func: anymore; just say usb_register() and the
> right things will happen.  Definitely worth fixing while you are in the
> neighborhood.
> ...
> If you're making this change, take out "the" (as well as :c:func:).
> ...
> ___
> 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

Alan Stern