Skip to contentSkip to conversation

docs: driver-api: virtio: documentation improv suggestion

PATCH In review Bagas Sanjaya 2 participants 5 messages Dec 20, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover docs: driver-api: virtio: documentation improv suggestion

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/[email protected]/
[2]: https://lore.kernel.org/linux-doc/[email protected]/
[3]: https://lore.kernel.org/lkml/[email protected]/

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(-)
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

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

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

While at it, describe the second target.

---
 Documentation/driver-api/virtio/virtio.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
Documentation/driver-api/virtio/virtio.rst +5 -4
index 70b3aa6bcf5518..2e4ac9557f4a9f 100644
@@ -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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

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

In reply to Bagas Sanjaya

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

---
 Documentation/driver-api/virtio/virtio.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/driver-api/virtio/virtio.rst +4 -4
index 2e4ac9557f4a9f..88e2a9bcd8b3f7 100644
@@ -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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw

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

In reply to 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).

---
 Documentation/driver-api/virtio/virtio.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/driver-api/virtio/virtio.rst +1 -1
index 88e2a9bcd8b3f7..7947b4ca690efd 100644
@@ -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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw
In reply to Bagas Sanjaya
Quoted 11 lines · 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/[email protected]/
[2]: https://lore.kernel.org/linux-doc/[email protected]/
[3]: https://lore.kernel.org/lkml/[email protected]/

Thanks, will queue for rc2.

Quoted 11 lines

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(-)
Signature · 1 line
An old man doll... just what I always wanted! - Clara

_______________________________________________
Virtualization mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/virtualization