remove unnecessary words in function documention
cover remove unnecessary words in function documention
The phrase "This API is used to" is unnecessary and changes the documentation into passive voice.
Stephen Hemminger (2):
rawdev, dmadev: remove passive voice in function doc
eal: remove passive voice from interrupt function documentation
drivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- lib/eal/include/rte_interrupts.h | 23 +++++++++++------------ 3 files changed, 13 insertions(+), 14 deletions(-)
Signature · 1 line
2.35.1
PATCH 1/2 rawdev, dmadev: remove passive voice in function doc
Remove extraneous phrase "This API is used to" and use active instead of passive voice when describing a function.
--- drivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)
drivers/raw/ioat/rte_ioat_rawdev.h +1 -1
@@ -123,7 +123,7 @@ rte_ioat_fence(int dev_id);/** * Trigger hardware to begin performing enqueued operations * -* This API is used to write the "doorbell" to the hardware to trigger it +* Writes the "doorbell" to the hardware to trigger it * to begin the operations previously enqueued by rte_ioat_enqueue_copy() * * @param dev_id
lib/dmadev/rte_dmadev.h +1 -1
@@ -970,7 +970,7 @@ rte_dma_fill(int16_t dev_id, uint16_t vchan, uint64_t pattern,* * Trigger hardware to begin performing enqueued operations. * -* This API is used to write the "doorbell" to the hardware to trigger it +* Writes the "doorbell" to the hardware to trigger it * to begin the operations previously enqueued by rte_dma_copy/fill(). * * @param dev_id
Signature · 1 line
2.35.1
Re: [PATCH 1/2] rawdev, dmadev: remove passive voice in function doc
Quoted 36 lines · Stephen Hemminger
Remove extraneous phrase "This API is used to" and use active instead of passive voice when describing a function.
Signed-off-by Stephen Hemminger <[email protected]>--- drivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)drivers/raw/ioat/rte_ioat_rawdev.h +1
-1@@ -123,7 +123,7 @@ rte_ioat_fence(int dev_id);/** * Trigger hardware to begin performing enqueued operations * -* This API is used to write the "doorbell" to the hardware to trigger it +* Writes the "doorbell" to the hardware to trigger it * to begin the operations previously enqueued by rte_ioat_enqueue_copy() * * @param dev_id lib/dmadev/rte_dmadev.h +1
-1@@ -970,7 +970,7 @@ rte_dma_fill(int16_t dev_id, uint16_t vchan, uint64_t pattern,* * Trigger hardware to begin performing enqueued operations. * -* This API is used to write the "doorbell" to the hardware to trigger it +* Writes the "doorbell" to the hardware to trigger it * to begin the operations previously enqueued by rte_dma_copy/fill(). * * @param dev_id
RE: [PATCH 1/2] rawdev, dmadev: remove passive voice in function doc
In reply to Stephen HemmingerQuoted 29 lines
Remove extraneous phrase "This API is used to" and use active instead of passive voice when describing a function.
Signed-off-by Stephen Hemminger <[email protected]>--- drivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)drivers/raw/ioat/rte_ioat_rawdev.h +1
-1@@ -123,7 +123,7 @@ rte_ioat_fence(int dev_id);/** * Trigger hardware to begin performing enqueued operations * -* This API is used to write the "doorbell" to the hardware to trigger it +* Writes the "doorbell" to the hardware to trigger it * to begin the operations previously enqueued by rte_ioat_enqueue_copy() * * @param
dev_idlib/dmadev/rte_dmadev.h +0
-0
lib/dmadev/rte_dmadev.h rte_dma_fill(int16_t dev_id, uint16_t vchan, uint64_t · line 975
Quoted 7 lines
lib/dmadev/rte_dmadev.h +1
-1@@ -970,7 +970,7 @@ rte_dma_fill(int16_t dev_id, uint16_t vchan, uint64_t pattern, * * Trigger hardware to begin performing enqueued operations. * - * This API is used to write the "doorbell" to the hardware to trigger it + * Writes the "doorbell" to the hardware to trigger it * to begin the operations previously enqueued by rte_dma_copy/fill().
I understand that this change was probably done like this to have the smallest diff, but should these lines be rewrapped. Its minor anyway so it doesn't really matter but it just looks strange to me the way it is.
With or without suggestion:
Quoted 4 lines
lib/dmadev/rte_dmadev.h +0
-0* * @param
dev_id
--
2.35.1
PATCH 2/2 eal: remove passive voice from interrupt function documentation
In reply to Stephen HemmingerThe phrase "This API is used" is unnecessary, remove it. Reword to describe function in active voice.
--- lib/eal/include/rte_interrupts.h | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-)
lib/eal/include/rte_interrupts.h +11 -12
@@ -239,8 +239,7 @@ rte_intr_instance_alloc(uint32_t flags);* @warning * @b EXPERIMENTAL: this API may change without prior notice * -* This API is used to free the memory allocated for interrupt handle -* resources. +* Free the memory allocated for interrupt handle resources. * * @param intr_handle * Interrupt handle address.
@@ -254,7 +253,7 @@ rte_intr_instance_free(struct rte_intr_handle *intr_handle);* @warning * @b EXPERIMENTAL: this API may change without prior notice * -* This API is used to set the fd field of interrupt handle with user provided +* Set the fd field of interrupt handle with user provided * file descriptor. * * @param intr_handle
@@ -291,7 +290,7 @@ rte_intr_fd_get(const struct rte_intr_handle *intr_handle);* @warning * @b EXPERIMENTAL: this API may change without prior notice * -* This API is used to set the type field of interrupt handle with user provided +* Set the type field of interrupt handle with user provided * interrupt type. * * @param intr_handle
@@ -452,7 +451,7 @@ rte_intr_instance_dup(const struct rte_intr_handle *src);/** * @internal -* This API is used to set the device fd field of interrupt handle with user +* Set the device fd field of interrupt handle with user * provided dev fd. Device fd corresponds to VFIO device fd or UIO config fd. * * @param intr_handle
@@ -485,7 +484,7 @@ rte_intr_dev_fd_get(const struct rte_intr_handle *intr_handle);/** * @internal -* This API is used to set the max intr field of interrupt handle with user +* Set the max intr field of interrupt handle with user * provided max intr value. * * @param intr_handle
@@ -518,7 +517,7 @@ rte_intr_max_intr_get(const struct rte_intr_handle *intr_handle);/** * @internal -* This API is used to set the number of event fd field of interrupt handle +* Set the number of event fd field of interrupt handle * with user provided available event file descriptor value. * * @param intr_handle
@@ -572,7 +571,7 @@ rte_intr_nb_intr_get(const struct rte_intr_handle *intr_handle);/** * @internal -* This API is used to set the event fd counter size field of interrupt handle +* Set the event fd counter size field of interrupt handle * with user provided efd counter size. * * @param intr_handle
@@ -607,7 +606,7 @@ rte_intr_efd_counter_size_get(const struct rte_intr_handle *intr_handle);/** * @internal -* This API is used to set the event fd array index with the given fd. +* Set the event fd array index with the given fd. * * @param intr_handle * pointer to the interrupt handle.
@@ -643,7 +642,7 @@ rte_intr_efds_index_get(const struct rte_intr_handle *intr_handle, int index);/** * @internal -* This API is used to set the epoll event object array index with the given +* Set the epoll event object array index with the given * elist instance. * * @param intr_handle
@@ -779,7 +778,7 @@ rte_intr_event_list_update(struct rte_intr_handle *intr_handle, int size);/** * @internal -* This API returns the Windows handle of the given interrupt instance. +* Returns the Windows handle of the given interrupt instance. * * @param intr_handle * pointer to the interrupt handle.
@@ -794,7 +793,7 @@ rte_intr_instance_windows_handle_get(struct rte_intr_handle *intr_handle);/** * @internal -* This API set the Windows handle for the given interrupt instance. +* Set the Windows handle for the given interrupt instance. * * @param intr_handle * pointer to the interrupt handle.
Signature · 1 line
2.35.1
Quoted 13 lines · Stephen Hemminger
The phrase "This API is used to" is unnecessary and changes the documentation into passive voice.
Stephen Hemminger (2):
rawdev, dmadev: remove passive voice in function doc
eal: remove passive voice from interrupt function documentationdrivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- lib/eal/include/rte_interrupts.h | 23 +++++++++++------------ 3 files changed, 13 insertions(+), 14 deletions(-)
the re-wording has shortened some of the lines, i'm not sure what takes precedence (minimum diff vs line length convention).
whatever is decided lgtm
Quoted 13 lines · On Wed, 22 Jun 2022 13:37:12 -0700 Tyler Retzlaff…
Quoted 12 lines · Stephen Hemminger
The phrase "This API is used to" is unnecessary and changes the documentation into passive voice.
Stephen Hemminger (2):
rawdev, dmadev: remove passive voice in function doc
eal: remove passive voice from interrupt function documentationdrivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- lib/eal/include/rte_interrupts.h | 23 +++++++++++------------ 3 files changed, 13 insertions(+), 14 deletions(-)
Quoted 5 lines
Quoted 1 line
the re-wording has shortened some of the lines, i'm not sure what takes precedence (minimum diff vs line length convention).
Doxygen repacks line during documentation generation
Quoted 16 lines · Stephen Hemminger
Quoted 13 lines · On Wed, 22 Jun 2022 13:37:12 -0700 Tyler Retzlaff…
Quoted 12 lines · Stephen Hemminger
The phrase "This API is used to" is unnecessary and changes the documentation into passive voice.
Stephen Hemminger (2):
rawdev, dmadev: remove passive voice in function doc
eal: remove passive voice from interrupt function documentationdrivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- lib/eal/include/rte_interrupts.h | 23 +++++++++++------------ 3 files changed, 13 insertions(+), 14 deletions(-)
Quoted 7 lines
Quoted 5 lines
Quoted 1 line
the re-wording has shortened some of the lines, i'm not sure what takes precedence (minimum diff vs line length convention).
Doxygen repacks line during documentation generation
no worries either way, myself i don't read doxygen i read the code/comments directly.
David Marchand
AppliedQuoted 4 lines · Stephen Hemminger
The phrase "This API is used to" is unnecessary and changes the documentation into passive voice.
Quoted 8 lines
Stephen Hemminger (2):
rawdev, dmadev: remove passive voice in function doc
eal: remove passive voice from interrupt function documentationdrivers/raw/ioat/rte_ioat_rawdev.h | 2 +- lib/dmadev/rte_dmadev.h | 2 +- lib/eal/include/rte_interrupts.h | 23 +++++++++++------------ 3 files changed, 13 insertions(+), 14 deletions(-)
Applied, thanks.
Signature · 1 line
David Marchand