[PATCH 0/2] remove unnecessary words in function documention

[PATCH 0/2] remove unnecessary words in function documention

[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(-)

-- 
2.35.1

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

[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 <stephen@networkplumber.org>
---
 drivers/raw/ioat/rte_ioat_rawdev.h | 2 +-
 lib/dmadev/rte_dmadev.h            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/raw/ioat/rte_ioat_rawdev.h b/drivers/raw/ioat/rte_ioat_rawdev.h
index 6cc1560a6402..0e79f754723d 100644
--- a/drivers/raw/ioat/rte_ioat_rawdev.h
+++ b/drivers/raw/ioat/rte_ioat_rawdev.h
@@ -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
diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
index a7081e633c2a..e7f992b734fc 100644
--- a/lib/dmadev/rte_dmadev.h
+++ b/lib/dmadev/rte_dmadev.h
@@ -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
-- 
2.35.1

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

[fengchengwen]

Acked-by: Chengwen Feng <fengchengwen@huawei.com>

On 2022/6/23 4:27, Stephen Hemminger wrote:
> Remove extraneous phrase "This API is used to" and use
> active instead of passive voice when describing a function.
> 
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> ---
>  drivers/raw/ioat/rte_ioat_rawdev.h | 2 +-
>  lib/dmadev/rte_dmadev.h            | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/raw/ioat/rte_ioat_rawdev.h b/drivers/raw/ioat/rte_ioat_rawdev.h
> index 6cc1560a6402..0e79f754723d 100644
> --- a/drivers/raw/ioat/rte_ioat_rawdev.h
> +++ b/drivers/raw/ioat/rte_ioat_rawdev.h
> @@ -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
> diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
> index a7081e633c2a..e7f992b734fc 100644
> --- a/lib/dmadev/rte_dmadev.h
> +++ b/lib/dmadev/rte_dmadev.h
> @@ -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

[Walsh, Conor]

> Remove extraneous phrase "This API is used to" and use
> active instead of passive voice when describing a function.
> 
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> ---
>  drivers/raw/ioat/rte_ioat_rawdev.h | 2 +-
>  lib/dmadev/rte_dmadev.h            | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/raw/ioat/rte_ioat_rawdev.h
> b/drivers/raw/ioat/rte_ioat_rawdev.h
> index 6cc1560a6402..0e79f754723d 100644
> --- a/drivers/raw/ioat/rte_ioat_rawdev.h
> +++ b/drivers/raw/ioat/rte_ioat_rawdev.h
> @@ -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
> diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
> index a7081e633c2a..e7f992b734fc 100644
> --- a/lib/dmadev/rte_dmadev.h
> +++ b/lib/dmadev/rte_dmadev.h
> @@ -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:
Acked-by: Conor Walsh <conor.walsh@intel.com>

>   *
>   * @param dev_id
> --
> 2.35.1

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

[Stephen Hemminger]

The phrase "This API is used" is unnecessary, remove it.
Reword to describe function in active voice.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 lib/eal/include/rte_interrupts.h | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/lib/eal/include/rte_interrupts.h b/lib/eal/include/rte_interrupts.h
index edbf0faeeffd..68ad19c3e742 100644
--- a/lib/eal/include/rte_interrupts.h
+++ b/lib/eal/include/rte_interrupts.h
@@ -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.
-- 
2.35.1

Re: [PATCH 0/2] remove unnecessary words in function documention

[Tyler Retzlaff]

On Wed, Jun 22, 2022 at 01:27:36PM -0700, Stephen Hemminger wrote:
> 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

Series-acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>

Re: [PATCH 0/2] remove unnecessary words in function documention

[Stephen Hemminger]

On Wed, 22 Jun 2022 13:37:12 -0700
Tyler Retzlaff <roretzla@linux.microsoft.com> wrote:

> On Wed, Jun 22, 2022 at 01:27:36PM -0700, Stephen Hemminger wrote:
> > 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).
> 

Doxygen repacks line during documentation generation

Re: [PATCH 0/2] remove unnecessary words in function documention

[Tyler Retzlaff]

On Wed, Jun 22, 2022 at 01:54:46PM -0700, Stephen Hemminger wrote:
> On Wed, 22 Jun 2022 13:37:12 -0700
> Tyler Retzlaff <roretzla@linux.microsoft.com> wrote:
> 
> > On Wed, Jun 22, 2022 at 01:27:36PM -0700, Stephen Hemminger wrote:
> > > 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).
> > 
> 
> Doxygen repacks line during documentation generation

no worries either way, myself i don't read doxygen i read the
code/comments directly.

Re: [PATCH 0/2] remove unnecessary words in function documention

[David Marchand]

On Wed, Jun 22, 2022 at 10:27 PM Stephen Hemminger
<stephen@networkplumber.org> wrote:
>
> 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(-)

Applied, thanks.


-- 
David Marchand