diff mbox series

[1/2] complib/cl_event_wheel.h improve comment documentation

Message ID 20181102025321.25429-1-honli@redhat.com (mailing list archive)
State Not Applicable
Headers show
Series [1/2] complib/cl_event_wheel.h improve comment documentation | expand

Commit Message

Honggang LI Nov. 2, 2018, 2:53 a.m. UTC 
From: Honggang Li <honli@redhat.com>

Signed-off-by: Honggang Li <honli@redhat.com>
---
 include/complib/cl_event_wheel.h | 39 +++++++++++++++++++--------------------
 1 file changed, 19 insertions(+), 20 deletions(-)

Comments

Hal Rosenstock Nov. 2, 2018, 12:14 p.m. UTC | #1 
On 11/1/2018 10:53 PM, Honggang LI wrote:
> From: Honggang Li <honli@redhat.com>
> 
> Signed-off-by: Honggang Li <honli@redhat.com>
> ---
>  include/complib/cl_event_wheel.h | 39 +++++++++++++++++++--------------------
>  1 file changed, 19 insertions(+), 20 deletions(-)
> 
> diff --git a/include/complib/cl_event_wheel.h b/include/complib/cl_event_wheel.h
> index 48833532..836a8a33 100644
> --- a/include/complib/cl_event_wheel.h
> +++ b/include/complib/cl_event_wheel.h
> @@ -137,7 +137,6 @@ typedef uint64_t
>  typedef struct _cl_event_wheel {
>  	cl_spinlock_t lock;
>  	cl_spinlock_t *p_external_lock;
> -
>  	cl_qmap_t events_map;
>  	boolean_t closing;
>  	cl_qlist_t events_wheel;
> @@ -215,7 +214,7 @@ typedef struct _cl_event_wheel_reg_info {
>  *		Client's context for event-aged callback.
>  *
>  *	p_event_wheel
> -*		Pointer to this event wheel object
> +*		Pointer to parent event wheel object

The event wheel object is not the parent of the registration info.
Anyhow, this field is not used/needed. Patch to eliminate this to follow
shortly.

>  *
>  * SEE ALSO
>  *********/
> @@ -225,7 +224,7 @@ typedef struct _cl_event_wheel_reg_info {
>  *	cl_event_wheel_construct
>  *
>  * DESCRIPTION
> -*	This function constructs a Event_Wheel object.
> +*	This function constructs an Event_Wheel object.
>  *
>  * SYNOPSIS
>  */
> @@ -233,13 +232,13 @@ void cl_event_wheel_construct(IN cl_event_wheel_t * const p_event_wheel);
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  * RETURN VALUE
>  *	This function does not return a value.
>  *
>  * NOTES
> -*	Allows calling cl_event_wheel_init and cl_event_wheel_destroy.
> +*	Allows calling cl_event_wheel_destroy.

While strictly speaking, cl_event_wheel_init does not require a prior
cl_event_wheel_construct call, this is the general design pattern used.

>  *
>  * SEE ALSO
>  *	Event_Wheel, cl_event_wheel_init, cl_event_wheel_destroy
> @@ -250,7 +249,7 @@ void cl_event_wheel_construct(IN cl_event_wheel_t * const p_event_wheel);
>  *	cl_event_wheel_init
>  *
>  * DESCRIPTION
> -*	This function initializes a Event_Wheel object.
> +*	This function initializes an Event_Wheel object.
>  *
>  * SYNOPSIS
>  */
> @@ -260,7 +259,7 @@ cl_event_wheel_init(IN cl_event_wheel_t * const p_event_wheel);
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  * RETURN VALUE
>  *	CL_SUCCESS if the operation is successful.
> @@ -270,12 +269,12 @@ cl_event_wheel_init(IN cl_event_wheel_t * const p_event_wheel);
>  *
>  *********/
>  
> -/****f* Component Library: Event_Wheel/cl_event_wheel_init
> +/****f* Component Library: Event_Wheel/cl_event_wheel_init_ex
>  * NAME
> -*	cl_event_wheel_init
> +*	cl_event_wheel_init_ex
>  *
>  * DESCRIPTION
> -*	This function initializes a Event_Wheel object.
> +*	This function initializes an Event_Wheel object with an external spinlock
>  *
>  * SYNOPSIS
>  */
> @@ -286,7 +285,7 @@ cl_event_wheel_init_ex(IN cl_event_wheel_t * const p_event_wheel,
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  *	p_external_lock
>  *		[in] Reference to external spinlock to guard internal structures
> @@ -305,7 +304,7 @@ cl_event_wheel_init_ex(IN cl_event_wheel_t * const p_event_wheel,
>  *	cl_event_wheel_destroy
>  *
>  * DESCRIPTION
> -*	This function destroys a Event_Wheel object.
> +*	This function destroys an Event_Wheel object.
>  *
>  * SYNOPSIS
>  */
> @@ -313,7 +312,7 @@ void cl_event_wheel_destroy(IN cl_event_wheel_t * const p_event_wheel);
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  * RETURN VALUE
>  *	This function does not return a value.
> @@ -339,7 +338,7 @@ void cl_event_wheel_dump(IN cl_event_wheel_t * const p_event_wheel);
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  * RETURN VALUE
>  *	This function does not return a value.
> @@ -357,7 +356,7 @@ void cl_event_wheel_dump(IN cl_event_wheel_t * const p_event_wheel);
>  *	cl_event_wheel_reg
>  *
>  * DESCRIPTION
> -*	This function registers a client with a Event_Wheel object.
> +*	This function registers a client with an Event_Wheel object.
>  *
>  * SYNOPSIS
>  */
> @@ -370,7 +369,7 @@ cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  *	key
>  *		[in] The specifc Key by which events are registered.
> @@ -387,7 +386,7 @@ cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
>  *		function.
>  *
>  * RETURN VALUE
> -*	On success a Event_Wheel CL_SUCCESS or CL_ERROR otherwise.
> +*	On success an Event_Wheel CL_SUCCESS or CL_ERROR otherwise.
>  *
>  * SEE ALSO
>  *	Event_Wheel, cl_event_wheel_unreg
> @@ -398,7 +397,7 @@ cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
>  *	cl_event_wheel_unreg
>  *
>  * DESCRIPTION
> -*	This function unregisters a client event from a Event_Wheel.
> +*	This function unregisters a client event from an Event_Wheel.
>  *
>  * SYNOPSIS
>  */
> @@ -408,7 +407,7 @@ cl_event_wheel_unreg(IN cl_event_wheel_t * const p_event_wheel,
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  *	key
>  *		[in] The key used for registering the event
> @@ -440,7 +439,7 @@ cl_event_wheel_num_regs(IN cl_event_wheel_t * const p_event_wheel,
>  /*
>  * PARAMETERS
>  *	p_event_wheel
> -*		[in] Pointer to a Event_Wheel.
> +*		[in] Pointer to an Event_Wheel.
>  *
>  *	key
>  *		[in] The key used for registering the event
>
Honggang LI Nov. 2, 2018, 1:24 p.m. UTC | #2 
On Fri, Nov 02, 2018 at 08:14:39AM -0400, Hal Rosenstock wrote:
> On 11/1/2018 10:53 PM, Honggang LI wrote:
> > From: Honggang Li <honli@redhat.com>
> > 
> > Signed-off-by: Honggang Li <honli@redhat.com>
> > ---
> >  include/complib/cl_event_wheel.h | 39 +++++++++++++++++++--------------------
> >  1 file changed, 19 insertions(+), 20 deletions(-)
> > 
> > diff --git a/include/complib/cl_event_wheel.h b/include/complib/cl_event_wheel.h
> > index 48833532..836a8a33 100644
> > --- a/include/complib/cl_event_wheel.h
> > +++ b/include/complib/cl_event_wheel.h
> > @@ -137,7 +137,6 @@ typedef uint64_t
> >  typedef struct _cl_event_wheel {
> >  	cl_spinlock_t lock;
> >  	cl_spinlock_t *p_external_lock;
> > -
> >  	cl_qmap_t events_map;
> >  	boolean_t closing;
> >  	cl_qlist_t events_wheel;
> > @@ -215,7 +214,7 @@ typedef struct _cl_event_wheel_reg_info {
> >  *		Client's context for event-aged callback.
> >  *
> >  *	p_event_wheel
> > -*		Pointer to this event wheel object
> > +*		Pointer to parent event wheel object
> 
> The event wheel object is not the parent of the registration info.
> Anyhow, this field is not used/needed. Patch to eliminate this to follow
> shortly.

I acked your patch which eliminates 'p_event_wheel'.

> 
> >  *
> >  * SEE ALSO
> >  *********/
> > @@ -225,7 +224,7 @@ typedef struct _cl_event_wheel_reg_info {
> >  *	cl_event_wheel_construct
> >  *
> >  * DESCRIPTION
> > -*	This function constructs a Event_Wheel object.
> > +*	This function constructs an Event_Wheel object.
> >  *
> >  * SYNOPSIS
> >  */
> > @@ -233,13 +232,13 @@ void cl_event_wheel_construct(IN cl_event_wheel_t * const p_event_wheel);
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  * RETURN VALUE
> >  *	This function does not return a value.
> >  *
> >  * NOTES
> > -*	Allows calling cl_event_wheel_init and cl_event_wheel_destroy.
> > +*	Allows calling cl_event_wheel_destroy.
> 
> While strictly speaking, cl_event_wheel_init does not require a prior
> cl_event_wheel_construct call, this is the general design pattern used.

Well, as I replied in the second patch, you should update
cl_event_wheel_init to call cl_event_wheel_construct.

> 
> >  *
> >  * SEE ALSO
> >  *	Event_Wheel, cl_event_wheel_init, cl_event_wheel_destroy
> > @@ -250,7 +249,7 @@ void cl_event_wheel_construct(IN cl_event_wheel_t * const p_event_wheel);
> >  *	cl_event_wheel_init
> >  *
> >  * DESCRIPTION
> > -*	This function initializes a Event_Wheel object.
> > +*	This function initializes an Event_Wheel object.
> >  *
> >  * SYNOPSIS
> >  */
> > @@ -260,7 +259,7 @@ cl_event_wheel_init(IN cl_event_wheel_t * const p_event_wheel);
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  * RETURN VALUE
> >  *	CL_SUCCESS if the operation is successful.
> > @@ -270,12 +269,12 @@ cl_event_wheel_init(IN cl_event_wheel_t * const p_event_wheel);
> >  *
> >  *********/
> >  
> > -/****f* Component Library: Event_Wheel/cl_event_wheel_init
> > +/****f* Component Library: Event_Wheel/cl_event_wheel_init_ex
> >  * NAME
> > -*	cl_event_wheel_init
> > +*	cl_event_wheel_init_ex
> >  *
> >  * DESCRIPTION
> > -*	This function initializes a Event_Wheel object.
> > +*	This function initializes an Event_Wheel object with an external spinlock
> >  *
> >  * SYNOPSIS
> >  */
> > @@ -286,7 +285,7 @@ cl_event_wheel_init_ex(IN cl_event_wheel_t * const p_event_wheel,
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  *	p_external_lock
> >  *		[in] Reference to external spinlock to guard internal structures
> > @@ -305,7 +304,7 @@ cl_event_wheel_init_ex(IN cl_event_wheel_t * const p_event_wheel,
> >  *	cl_event_wheel_destroy
> >  *
> >  * DESCRIPTION
> > -*	This function destroys a Event_Wheel object.
> > +*	This function destroys an Event_Wheel object.
> >  *
> >  * SYNOPSIS
> >  */
> > @@ -313,7 +312,7 @@ void cl_event_wheel_destroy(IN cl_event_wheel_t * const p_event_wheel);
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  * RETURN VALUE
> >  *	This function does not return a value.
> > @@ -339,7 +338,7 @@ void cl_event_wheel_dump(IN cl_event_wheel_t * const p_event_wheel);
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  * RETURN VALUE
> >  *	This function does not return a value.
> > @@ -357,7 +356,7 @@ void cl_event_wheel_dump(IN cl_event_wheel_t * const p_event_wheel);
> >  *	cl_event_wheel_reg
> >  *
> >  * DESCRIPTION
> > -*	This function registers a client with a Event_Wheel object.
> > +*	This function registers a client with an Event_Wheel object.
> >  *
> >  * SYNOPSIS
> >  */
> > @@ -370,7 +369,7 @@ cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  *	key
> >  *		[in] The specifc Key by which events are registered.
> > @@ -387,7 +386,7 @@ cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
> >  *		function.
> >  *
> >  * RETURN VALUE
> > -*	On success a Event_Wheel CL_SUCCESS or CL_ERROR otherwise.
> > +*	On success an Event_Wheel CL_SUCCESS or CL_ERROR otherwise.
> >  *
> >  * SEE ALSO
> >  *	Event_Wheel, cl_event_wheel_unreg
> > @@ -398,7 +397,7 @@ cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
> >  *	cl_event_wheel_unreg
> >  *
> >  * DESCRIPTION
> > -*	This function unregisters a client event from a Event_Wheel.
> > +*	This function unregisters a client event from an Event_Wheel.
> >  *
> >  * SYNOPSIS
> >  */
> > @@ -408,7 +407,7 @@ cl_event_wheel_unreg(IN cl_event_wheel_t * const p_event_wheel,
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  *	key
> >  *		[in] The key used for registering the event
> > @@ -440,7 +439,7 @@ cl_event_wheel_num_regs(IN cl_event_wheel_t * const p_event_wheel,
> >  /*
> >  * PARAMETERS
> >  *	p_event_wheel
> > -*		[in] Pointer to a Event_Wheel.
> > +*		[in] Pointer to an Event_Wheel.
> >  *
> >  *	key
> >  *		[in] The key used for registering the event
> >
diff mbox series

Patch

diff --git a/include/complib/cl_event_wheel.h b/include/complib/cl_event_wheel.h
index 48833532..836a8a33 100644
--- a/include/complib/cl_event_wheel.h
+++ b/include/complib/cl_event_wheel.h
@@ -137,7 +137,6 @@  typedef uint64_t
 typedef struct _cl_event_wheel {
 	cl_spinlock_t lock;
 	cl_spinlock_t *p_external_lock;
-
 	cl_qmap_t events_map;
 	boolean_t closing;
 	cl_qlist_t events_wheel;
@@ -215,7 +214,7 @@  typedef struct _cl_event_wheel_reg_info {
 *		Client's context for event-aged callback.
 *
 *	p_event_wheel
-*		Pointer to this event wheel object
+*		Pointer to parent event wheel object
 *
 * SEE ALSO
 *********/
@@ -225,7 +224,7 @@  typedef struct _cl_event_wheel_reg_info {
 *	cl_event_wheel_construct
 *
 * DESCRIPTION
-*	This function constructs a Event_Wheel object.
+*	This function constructs an Event_Wheel object.
 *
 * SYNOPSIS
 */
@@ -233,13 +232,13 @@  void cl_event_wheel_construct(IN cl_event_wheel_t * const p_event_wheel);
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 * RETURN VALUE
 *	This function does not return a value.
 *
 * NOTES
-*	Allows calling cl_event_wheel_init and cl_event_wheel_destroy.
+*	Allows calling cl_event_wheel_destroy.
 *
 * SEE ALSO
 *	Event_Wheel, cl_event_wheel_init, cl_event_wheel_destroy
@@ -250,7 +249,7 @@  void cl_event_wheel_construct(IN cl_event_wheel_t * const p_event_wheel);
 *	cl_event_wheel_init
 *
 * DESCRIPTION
-*	This function initializes a Event_Wheel object.
+*	This function initializes an Event_Wheel object.
 *
 * SYNOPSIS
 */
@@ -260,7 +259,7 @@  cl_event_wheel_init(IN cl_event_wheel_t * const p_event_wheel);
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 * RETURN VALUE
 *	CL_SUCCESS if the operation is successful.
@@ -270,12 +269,12 @@  cl_event_wheel_init(IN cl_event_wheel_t * const p_event_wheel);
 *
 *********/
 
-/****f* Component Library: Event_Wheel/cl_event_wheel_init
+/****f* Component Library: Event_Wheel/cl_event_wheel_init_ex
 * NAME
-*	cl_event_wheel_init
+*	cl_event_wheel_init_ex
 *
 * DESCRIPTION
-*	This function initializes a Event_Wheel object.
+*	This function initializes an Event_Wheel object with an external spinlock
 *
 * SYNOPSIS
 */
@@ -286,7 +285,7 @@  cl_event_wheel_init_ex(IN cl_event_wheel_t * const p_event_wheel,
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 *	p_external_lock
 *		[in] Reference to external spinlock to guard internal structures
@@ -305,7 +304,7 @@  cl_event_wheel_init_ex(IN cl_event_wheel_t * const p_event_wheel,
 *	cl_event_wheel_destroy
 *
 * DESCRIPTION
-*	This function destroys a Event_Wheel object.
+*	This function destroys an Event_Wheel object.
 *
 * SYNOPSIS
 */
@@ -313,7 +312,7 @@  void cl_event_wheel_destroy(IN cl_event_wheel_t * const p_event_wheel);
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 * RETURN VALUE
 *	This function does not return a value.
@@ -339,7 +338,7 @@  void cl_event_wheel_dump(IN cl_event_wheel_t * const p_event_wheel);
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 * RETURN VALUE
 *	This function does not return a value.
@@ -357,7 +356,7 @@  void cl_event_wheel_dump(IN cl_event_wheel_t * const p_event_wheel);
 *	cl_event_wheel_reg
 *
 * DESCRIPTION
-*	This function registers a client with a Event_Wheel object.
+*	This function registers a client with an Event_Wheel object.
 *
 * SYNOPSIS
 */
@@ -370,7 +369,7 @@  cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 *	key
 *		[in] The specifc Key by which events are registered.
@@ -387,7 +386,7 @@  cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
 *		function.
 *
 * RETURN VALUE
-*	On success a Event_Wheel CL_SUCCESS or CL_ERROR otherwise.
+*	On success an Event_Wheel CL_SUCCESS or CL_ERROR otherwise.
 *
 * SEE ALSO
 *	Event_Wheel, cl_event_wheel_unreg
@@ -398,7 +397,7 @@  cl_event_wheel_reg(IN cl_event_wheel_t * const p_event_wheel,
 *	cl_event_wheel_unreg
 *
 * DESCRIPTION
-*	This function unregisters a client event from a Event_Wheel.
+*	This function unregisters a client event from an Event_Wheel.
 *
 * SYNOPSIS
 */
@@ -408,7 +407,7 @@  cl_event_wheel_unreg(IN cl_event_wheel_t * const p_event_wheel,
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 *	key
 *		[in] The key used for registering the event
@@ -440,7 +439,7 @@  cl_event_wheel_num_regs(IN cl_event_wheel_t * const p_event_wheel,
 /*
 * PARAMETERS
 *	p_event_wheel
-*		[in] Pointer to a Event_Wheel.
+*		[in] Pointer to an Event_Wheel.
 *
 *	key
 *		[in] The key used for registering the event