Skip to contentSkip to conversation

remove unnecessary words in function documention

PATCH Applied Stephen Hemminger 5 participants 9 messages Jun 22, 2022 – Jun 24, 2022

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 6cc1560a6402..0e79f754723d 100644
@@ -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
index a7081e633c2a..e7f992b734fc 100644
@@ -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
Acked-by on v1 1/2
#2 lore raw

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.

---
 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
index 6cc1560a6402..0e79f754723d 100644
@@ -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
index a7081e633c2a..e7f992b734fc 100644
@@ -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
Acked-by on v1 1/2
#3 lore raw

RE: [PATCH 1/2] rawdev, dmadev: remove passive voice in function doc

In reply to Stephen Hemminger
Quoted 29 lines

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
index 6cc1560a6402..0e79f754723d 100644
@@ -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 +0 -0
index a7081e633c2a..e7f992b734fc 100644

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

#4 lore raw

PATCH 2/2 eal: remove passive voice from interrupt function documentation

In reply to Stephen Hemminger

The 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
index edbf0faeeffd..68ad19c3e742 100644
@@ -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
#5 lore raw
In reply to Stephen Hemminger
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 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(-)

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

#6 lore raw
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 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(-)
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

#7 lore raw
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 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(-)
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.

#8 lore raw
In reply to Stephen Hemminger
Quoted 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 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(-)

Applied, thanks.

Signature · 1 line
David Marchand