[PATCH 0/3] docs: driver-api: virtio: documentation improv suggestion

[PATCH 0/3] docs: driver-api: virtio: documentation improv suggestion

[Bagas Sanjaya]

Michael S. Tsirkin has asked me [1] to post my improv suggestions for
now-applied virtio documentation [2], so here is the suggestion patch series.
The original suggestion must be splitted since it contains three distinct
changes.

This series is based on kernel-doc fixup posted to fix recent linux-next
warnings [3].

[1]: https://lore.kernel.org/linux-doc/20221219011647-mutt-send-email-mst@kernel.org/
[2]: https://lore.kernel.org/linux-doc/Y0QYTq7KW9C731s0@debian.me/
[3]: https://lore.kernel.org/lkml/20221220073709.2687151-1-ricardo.canuelo@collabora.com/

Bagas Sanjaya (3):
  docs: driver-api: virtio: parenthesize external reference targets
  docs: driver-api: virtio: slightly reword virtqueues allocation
    paragraph
  docs: driver-api: virtio: commentize spec version checking

 Documentation/driver-api/virtio/virtio.rst | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/3] docs: driver-api: virtio: parenthesize external reference targets

[Bagas Sanjaya]

Parenthesize targets to links in "References" section to distinguish
them from remaining texts.

While at it, describe the second target.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/driver-api/virtio/virtio.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/virtio/virtio.rst b/Documentation/driver-api/virtio/virtio.rst
index 70b3aa6bcf5518..2e4ac9557f4a9f 100644
--- a/Documentation/driver-api/virtio/virtio.rst
+++ b/Documentation/driver-api/virtio/virtio.rst
@@ -11,7 +11,7 @@ Introduction
 
 Virtio is an open standard that defines a protocol for communication
 between drivers and devices of different types, see Chapter 5 ("Device
-Types") of the virtio spec `[1]`_. Originally developed as a standard
+Types") of the virtio spec (`[1]`_). Originally developed as a standard
 for paravirtualized devices implemented by a hypervisor, it can be used
 to interface any compliant device (real or emulated) with a driver.
 
@@ -43,9 +43,10 @@ similar to the ones used in a network device:
 All the buffers the descriptors point to are allocated by the guest and
 used by the host either for reading or for writing but not for both.
 
-Refer to Chapter 2.5 ("Virtqueues") of the virtio spec `[1]`_ for the
-reference definitions of virtqueues and to `[2]`_ for an illustrated
-overview of how the host device and the guest driver communicate.
+Refer to Chapter 2.5 ("Virtqueues") of the virtio spec (`[1]`_) for the
+reference definitions of virtqueues and "Virtqueues and virtio ring: How
+the data travels" blog post (`[2]`_) for an illustrated overview of how
+the host device and the guest driver communicate.
 
 The :c:type:`vring_virtqueue` struct models a virtqueue, including the
 ring buffers and management data. Embedded in this struct is the
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/3] docs: driver-api: virtio: slightly reword virtqueues allocation paragraph

[Bagas Sanjaya]

"It's at this stage that" means "At this point", so use the latter as it
is more effective.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/driver-api/virtio/virtio.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/virtio/virtio.rst b/Documentation/driver-api/virtio/virtio.rst
index 2e4ac9557f4a9f..88e2a9bcd8b3f7 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.
 
-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.
+At this point, 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.
 
 
 References
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 3/3] docs: driver-api: virtio: commentize spec version checking

[Bagas Sanjaya]

A sentence that checks for later spec version is meant for developers
hacking the documentation source. Make it comment block (hidden from
actual output).

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/driver-api/virtio/virtio.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/virtio/virtio.rst b/Documentation/driver-api/virtio/virtio.rst
index 88e2a9bcd8b3f7..7947b4ca690efd 100644
--- a/Documentation/driver-api/virtio/virtio.rst
+++ b/Documentation/driver-api/virtio/virtio.rst
@@ -135,7 +135,7 @@ References
 _`[1]` Virtio Spec v1.2:
 https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
 
-Check for later versions of the spec as well.
+.. Check for later versions of the spec as well.
 
 _`[2]` Virtqueues and virtio ring: How the data travels
 https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 0/3] docs: driver-api: virtio: documentation improv suggestion

[Michael S. Tsirkin]

On Tue, Dec 20, 2022 at 04:58:26PM +0700, Bagas Sanjaya wrote:
> Michael S. Tsirkin has asked me [1] to post my improv suggestions for
> now-applied virtio documentation [2], so here is the suggestion patch series.
> The original suggestion must be splitted since it contains three distinct
> changes.
> 
> This series is based on kernel-doc fixup posted to fix recent linux-next
> warnings [3].
> 
> [1]: https://lore.kernel.org/linux-doc/20221219011647-mutt-send-email-mst@kernel.org/
> [2]: https://lore.kernel.org/linux-doc/Y0QYTq7KW9C731s0@debian.me/
> [3]: https://lore.kernel.org/lkml/20221220073709.2687151-1-ricardo.canuelo@collabora.com/

Thanks, will queue for rc2.

> Bagas Sanjaya (3):
>   docs: driver-api: virtio: parenthesize external reference targets
>   docs: driver-api: virtio: slightly reword virtqueues allocation
>     paragraph
>   docs: driver-api: virtio: commentize spec version checking
> 
>  Documentation/driver-api/virtio/virtio.rst | 19 ++++++++++---------
>  1 file changed, 10 insertions(+), 9 deletions(-)
> 
> -- 
> An old man doll... just what I always wanted! - Clara