Virtualization - Oct 2022 - [RESEND PATCH v5 1/1] docs: driver-api: virtio: virtio on Linux

Hi Bagas, thanks for the review, some comments below:

On lun, oct 10 2022 at 20:04:14, Bagas Sanjaya <bagasdotme at gmail.com>
wrote:
> What link is for [2]? I think you'll need to spell out the link title.
> Also, the external reference pointers should be parenthesized to indicate
> that these are references:
That's a matter of personal opinion and I disagree with it. There's no
consensus across the kernel docs and I'm using the IEEE style, which is
fairly standard.

>  The :c:type:`vring_virtqueue` struct models a virtqueue, including the
>  ring buffers and management data. Embedded in this struct is the
>
>
> Personally speaking, ReST citations should do the job better (these
> links are external references, right?).
I don't want to use a full ReST code reference for that, as that struct
is not really part of the interface for virtio drivers and its
definition is an implementation detail. But I still want to have it
properly formatted in the html and pdf outputs, that's why I'm using
:c:type: there.

>> +It's at this stage that the virtqueues will be allocated and
configured
>> +by calling the appropriate ``virtio_find`` helper function, such as
>> +virtio_find_single_vq() or virtio_find_vqs(), which will end up
>> +calling a transport-specific ``find_vqs`` method.
>> +
>
> Looks like the wording at the beginning confuses me, so better say:
>
> ---- >8 ----
> diff --git a/Documentation/driver-api/virtio/virtio.rst
b/Documentation/driver-api/virtio/virtio.rst
> index 07fd2d7c51e689..7947b4ca690efd 100644
> --- a/Documentation/driver-api/virtio/virtio.rst
> +++ b/Documentation/driver-api/virtio/virtio.rst
> @@ -123,10 +123,10 @@ When the device is registered to the virtio bus the
kernel will look
>  for a driver in the bus that can handle the device and call that
>  driver's ``probe`` method.
I think this is a matter of style as well, maybe a native speaker can
pitch in about the correctness of it.

Cheers,
Ricardo

On Tue, Oct 11, 2022 at 10:46:43AM +0200, Ricardo Ca?uelo
wrote:
> >> +It's at this stage that the virtqueues will be allocated and
configured
> >> +by calling the appropriate ``virtio_find`` helper function, such
as
> >> +virtio_find_single_vq() or virtio_find_vqs(), which will end up
> >> +calling a transport-specific ``find_vqs`` method.
> >> +
> >
> > Looks like the wording at the beginning confuses me, so better say:
> >
> > ---- >8 ----
> > diff --git a/Documentation/driver-api/virtio/virtio.rst
b/Documentation/driver-api/virtio/virtio.rst
> > index 07fd2d7c51e689..7947b4ca690efd 100644
> > --- a/Documentation/driver-api/virtio/virtio.rst
> > +++ b/Documentation/driver-api/virtio/virtio.rst
> > @@ -123,10 +123,10 @@ When the device is registered to the virtio bus
the kernel will look
> >  for a driver in the bus that can handle the device and call that
> >  driver's ``probe`` method.
> 
> I think this is a matter of style as well, maybe a native speaker can
> pitch in about the correctness of it.
> 
> Cheers,
> Ricardo
I think I agree with this comment.  This seems minor enough so I applied
the patch for now. Bagas would you like to post your suggestion as a patch on
top? Would be appreciated. Thanks!

-- 
MST