Subject: Re: [PATCH 1/4] Docs: usb: update usb_bulk_msg receiving example
To:     Alan Stern <stern@rowland.harvard.edu>
References: <cover.1638152984.git.philipp.g.hortmann@gmail.com>
 <28a76eedad7027277754cef84ca34810b0cfe6f4.1638152984.git.philipp.g.hortmann@gmail.com>
 <YaaFNO1t3GIaGFPI@rowland.harvard.edu>
From:   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
Message-ID: <ad2fcdfa-5688-4d09-2c82-c405adeae4ee@gmail.com>
Date:   Thu, 2 Dec 2021 05:49:47 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.14.0
MIME-Version: 1.0
In-Reply-To: <YaaFNO1t3GIaGFPI@rowland.harvard.edu>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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?
Thanks for your support.
Philipp Hortmann