From: Alan Stern <stern@rowland.harvard.edu>
To: Philipp Hortmann <philipp.g.hortmann@gmail.com>
Cc: corbet@lwn.net, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, linux-usb@vger.kernel.org
Subject: Re: [PATCH 1/4] Docs: usb: update usb_bulk_msg receiving example
Date: Thu, 2 Dec 2021 14:49:08 -0500 [thread overview]
Message-ID: <YakjNGEBFKm9pHCw@rowland.harvard.edu> (raw)
In-Reply-To: <ad2fcdfa-5688-4d09-2c82-c405adeae4ee@gmail.com>
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@gmail.com>
> > > ---
> > > .../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@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
Alan Stern
next prev parent reply other threads:[~2021-12-02 19:49 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-29 20:21 [PATCH 0/4] Docs: usb: Code and text updates from usb-skeleton Philipp Hortmann
2021-11-29 20:21 ` [PATCH 1/4] Docs: usb: update usb_bulk_msg receiving example Philipp Hortmann
2021-11-30 20:10 ` Alan Stern
2021-12-02 4:49 ` Philipp Hortmann
2021-12-02 19:49 ` Alan Stern [this message]
2021-12-03 2:01 ` Akira Yokosawa
2021-11-29 20:21 ` [PATCH 2/4] Docs: usb: update comment and code near decrement our usage count for the device Philipp Hortmann
2021-11-29 20:21 ` [PATCH 3/4] Docs: usb: update comment and code of function skel_delete Philipp Hortmann
2021-12-03 10:57 ` Greg KH
2021-11-29 20:21 ` [PATCH 4/4] Docs: usb: update explanation for device_present to disconnected Philipp Hortmann
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=YakjNGEBFKm9pHCw@rowland.harvard.edu \
--to=stern@rowland.harvard.edu \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-usb@vger.kernel.org \
--cc=philipp.g.hortmann@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).