docs: driver-api: virtio: documentation improv suggestion
Subsystems (2)
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
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
@@ -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
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
@@ -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
PATCH 3/3 docs: driver-api: virtio: commentize spec version checking
In reply to Bagas SanjayaA 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
@@ -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
Michael S. Tsirkin
maintainerQuoted 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 checkingDocumentation/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