api: odp_event.h: remove ODP_EVENT_TYPE_INVALID

Message ID 1422892843-7670-1-git-send-email-ola.liljedahl@linaro.org
State New
Headers show

Commit Message

Ola Liljedahl Feb. 2, 2015, 4 p.m.
Remove ODP_EVENT_TYPE_INVALID from odp_event.h.
Update description of odp_event_type(), is does not return
ODP_EVENT_TYPE_INVALID.
Remove ODP_POOL_TYPE_INVALID from odp_pool.h. It was defined to
ODP_EVENT_TYPE_INVALID.

Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
---
(This document/code contribution attached is provided under the terms of
agreement LES-LTM-21309)

 include/odp/api/event.h                               | 9 ++-------
 include/odp/api/pool.h                                | 2 --
 platform/linux-generic/include/odp/plat/event_types.h | 1 -
 3 files changed, 2 insertions(+), 10 deletions(-)

Comments

Ola Liljedahl Feb. 3, 2015, 8:48 a.m. | #1
On 3 February 2015 at 09:15, Savolainen, Petri (NSN - FI/Espoo)
<petri.savolainen@nsn.com> wrote:
>
>
>> -----Original Message-----
>> From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp-
>> bounces@lists.linaro.org] On Behalf Of ext Ola Liljedahl
>> Sent: Monday, February 02, 2015 6:01 PM
>> To: lng-odp@lists.linaro.org
>> Subject: [lng-odp] [PATCH] api: odp_event.h: remove ODP_EVENT_TYPE_INVALID
>>
>> Remove ODP_EVENT_TYPE_INVALID from odp_event.h.
>> Update description of odp_event_type(), is does not return
>> ODP_EVENT_TYPE_INVALID.
>> Remove ODP_POOL_TYPE_INVALID from odp_pool.h. It was defined to
>> ODP_EVENT_TYPE_INVALID.
>>
>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
>> ---
>> (This document/code contribution attached is provided under the terms of
>> agreement LES-LTM-21309)
>>
>>  include/odp/api/event.h                               | 9 ++-------
>>  include/odp/api/pool.h                                | 2 --
>>  platform/linux-generic/include/odp/plat/event_types.h | 1 -
>>  3 files changed, 2 insertions(+), 10 deletions(-)
>>
>> diff --git a/include/odp/api/event.h b/include/odp/api/event.h
>> index 50c031a..ce97bdc 100644
>> --- a/include/odp/api/event.h
>> +++ b/include/odp/api/event.h
>> @@ -36,11 +36,6 @@ extern "C" {
>>   */
>>
>>  /**
>> - * @def ODP_EVENT_TYPE_INVALID
>> - * Invalid event type
>> - */
>> -
>> -/**
>>   * @def ODP_EVENT_BUFFER
>>   * Buffer event
>>   */
>> @@ -61,11 +56,11 @@ extern "C" {
>>   */
>>
>>  /**
>> - * Event type
>> + * Return type of event
>
> Don't change the Doxygen brief description. Almost every function return something, no need to mention that in the brief description. The detail description is there for full description/sentences.
Most functions have side effects and it is the side effect you are
after. What they return is normally just a status code or other
information on how successful they were (e.g. number of items
processed or written etc) in that side effect. This function *only*
returns something with no side effects. Thus the difference in
description.

>
> Otherwise OK.
>
> -Petri
>
>
>>   *
>>   * @param event    Event handle
>>   *
>> - * @return Event type or ODP_EVENT_TYPE_INVALID
>> + * @return Event type
>>   */
>>  int odp_event_type(odp_event_t event);
>>
>> diff --git a/include/odp/api/pool.h b/include/odp/api/pool.h
>> index 1582102..d09d92e 100644
>> --- a/include/odp/api/pool.h
>> +++ b/include/odp/api/pool.h
>> @@ -79,8 +79,6 @@ typedef struct odp_pool_param_t {
>>
>>  } odp_pool_param_t;
>>
>> -/** Invalid pool type */
>> -#define ODP_POOL_TYPE_INVALID ODP_EVENT_TYPE_INVALID
>>  /** Packet pool*/
>>  #define ODP_POOL_PACKET       ODP_EVENT_PACKET
>>  /** Buffer pool */
>> diff --git a/platform/linux-generic/include/odp/plat/event_types.h
>> b/platform/linux-generic/include/odp/plat/event_types.h
>> index 4a0756b..c98d416 100644
>> --- a/platform/linux-generic/include/odp/plat/event_types.h
>> +++ b/platform/linux-generic/include/odp/plat/event_types.h
>> @@ -30,7 +30,6 @@ typedef odp_buffer_t odp_event_t;
>>
>>  #define ODP_EVENT_INVALID ODP_BUFFER_INVALID
>>
>> -#define ODP_EVENT_TYPE_INVALID (-1)
>>  #define ODP_EVENT_BUFFER         1
>>  #define ODP_EVENT_PACKET         2
>>  #define ODP_EVENT_TIMEOUT        3
>> --
>> 1.9.1
>>
>>
>> _______________________________________________
>> lng-odp mailing list
>> lng-odp@lists.linaro.org
>> http://lists.linaro.org/mailman/listinfo/lng-odp
Ola Liljedahl Feb. 3, 2015, 10:57 a.m. | #2
On 3 February 2015 at 11:56, Savolainen, Petri (NSN - FI/Espoo)
<petri.savolainen@nsn.com> wrote:
>
>
>> -----Original Message-----
>> From: ext Ola Liljedahl [mailto:ola.liljedahl@linaro.org]
>> Sent: Tuesday, February 03, 2015 10:49 AM
>> To: Savolainen, Petri (NSN - FI/Espoo)
>> Cc: lng-odp@lists.linaro.org
>> Subject: Re: [lng-odp] [PATCH] api: odp_event.h: remove
>> ODP_EVENT_TYPE_INVALID
>>
>> On 3 February 2015 at 09:15, Savolainen, Petri (NSN - FI/Espoo)
>> <petri.savolainen@nsn.com> wrote:
>> >
>> >
>> >> -----Original Message-----
>> >> From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp-
>> >> bounces@lists.linaro.org] On Behalf Of ext Ola Liljedahl
>> >> Sent: Monday, February 02, 2015 6:01 PM
>> >> To: lng-odp@lists.linaro.org
>> >> Subject: [lng-odp] [PATCH] api: odp_event.h: remove
>> ODP_EVENT_TYPE_INVALID
>> >>
>> >> Remove ODP_EVENT_TYPE_INVALID from odp_event.h.
>> >> Update description of odp_event_type(), is does not return
>> >> ODP_EVENT_TYPE_INVALID.
>> >> Remove ODP_POOL_TYPE_INVALID from odp_pool.h. It was defined to
>> >> ODP_EVENT_TYPE_INVALID.
>> >>
>> >> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
>> >> ---
>> >> (This document/code contribution attached is provided under the terms
>> of
>> >> agreement LES-LTM-21309)
>> >>
>> >>  include/odp/api/event.h                               | 9 ++-------
>> >>  include/odp/api/pool.h                                | 2 --
>> >>  platform/linux-generic/include/odp/plat/event_types.h | 1 -
>> >>  3 files changed, 2 insertions(+), 10 deletions(-)
>> >>
>> >> diff --git a/include/odp/api/event.h b/include/odp/api/event.h
>> >> index 50c031a..ce97bdc 100644
>> >> --- a/include/odp/api/event.h
>> >> +++ b/include/odp/api/event.h
>> >> @@ -36,11 +36,6 @@ extern "C" {
>> >>   */
>> >>
>> >>  /**
>> >> - * @def ODP_EVENT_TYPE_INVALID
>> >> - * Invalid event type
>> >> - */
>> >> -
>> >> -/**
>> >>   * @def ODP_EVENT_BUFFER
>> >>   * Buffer event
>> >>   */
>> >> @@ -61,11 +56,11 @@ extern "C" {
>> >>   */
>> >>
>> >>  /**
>> >> - * Event type
>> >> + * Return type of event
>> >
>> > Don't change the Doxygen brief description. Almost every function return
>> something, no need to mention that in the brief description. The detail
>> description is there for full description/sentences.
>> Most functions have side effects and it is the side effect you are
>> after. What they return is normally just a status code or other
>> information on how successful they were (e.g. number of items
>> processed or written etc) in that side effect. This function *only*
>> returns something with no side effects. Thus the difference in
>> description.
>
> When you browse or search through the doxygen API documentation. It would be nice to find the keyword pair "event type" easily (and consistently).
>
> Currently most "get" type functions are labeled either "Type_x param_y" or "Get type_x param_y" (in brief description). You can change it to "Get event type", or leave as is. But do not change to "Return param_y of type_x".
"get event type" is fine as well.


>
> -Petri
>
>
>
>>
>> >
>> > Otherwise OK.
>> >
>> > -Petri
>> >
>> >
>> >>   *
>> >>   * @param event    Event handle
>> >>   *
>> >> - * @return Event type or ODP_EVENT_TYPE_INVALID
>> >> + * @return Event type
>> >>   */
>> >>  int odp_event_type(odp_event_t event);
>> >>
>> >> diff --git a/include/odp/api/pool.h b/include/odp/api/pool.h
>> >> index 1582102..d09d92e 100644
>> >> --- a/include/odp/api/pool.h
>> >> +++ b/include/odp/api/pool.h
>> >> @@ -79,8 +79,6 @@ typedef struct odp_pool_param_t {
>> >>
>> >>  } odp_pool_param_t;
>> >>
>> >> -/** Invalid pool type */
>> >> -#define ODP_POOL_TYPE_INVALID ODP_EVENT_TYPE_INVALID
>> >>  /** Packet pool*/
>> >>  #define ODP_POOL_PACKET       ODP_EVENT_PACKET
>> >>  /** Buffer pool */
>> >> diff --git a/platform/linux-generic/include/odp/plat/event_types.h
>> >> b/platform/linux-generic/include/odp/plat/event_types.h
>> >> index 4a0756b..c98d416 100644
>> >> --- a/platform/linux-generic/include/odp/plat/event_types.h
>> >> +++ b/platform/linux-generic/include/odp/plat/event_types.h
>> >> @@ -30,7 +30,6 @@ typedef odp_buffer_t odp_event_t;
>> >>
>> >>  #define ODP_EVENT_INVALID ODP_BUFFER_INVALID
>> >>
>> >> -#define ODP_EVENT_TYPE_INVALID (-1)
>> >>  #define ODP_EVENT_BUFFER         1
>> >>  #define ODP_EVENT_PACKET         2
>> >>  #define ODP_EVENT_TIMEOUT        3
>> >> --
>> >> 1.9.1
>> >>
>> >>
>> >> _______________________________________________
>> >> lng-odp mailing list
>> >> lng-odp@lists.linaro.org
>> >> http://lists.linaro.org/mailman/listinfo/lng-odp

Patch

diff --git a/include/odp/api/event.h b/include/odp/api/event.h
index 50c031a..ce97bdc 100644
--- a/include/odp/api/event.h
+++ b/include/odp/api/event.h
@@ -36,11 +36,6 @@  extern "C" {
  */
 
 /**
- * @def ODP_EVENT_TYPE_INVALID
- * Invalid event type
- */
-
-/**
  * @def ODP_EVENT_BUFFER
  * Buffer event
  */
@@ -61,11 +56,11 @@  extern "C" {
  */
 
 /**
- * Event type
+ * Return type of event
  *
  * @param event    Event handle
  *
- * @return Event type or ODP_EVENT_TYPE_INVALID
+ * @return Event type
  */
 int odp_event_type(odp_event_t event);
 
diff --git a/include/odp/api/pool.h b/include/odp/api/pool.h
index 1582102..d09d92e 100644
--- a/include/odp/api/pool.h
+++ b/include/odp/api/pool.h
@@ -79,8 +79,6 @@  typedef struct odp_pool_param_t {
 
 } odp_pool_param_t;
 
-/** Invalid pool type */
-#define ODP_POOL_TYPE_INVALID ODP_EVENT_TYPE_INVALID
 /** Packet pool*/
 #define ODP_POOL_PACKET       ODP_EVENT_PACKET
 /** Buffer pool */
diff --git a/platform/linux-generic/include/odp/plat/event_types.h b/platform/linux-generic/include/odp/plat/event_types.h
index 4a0756b..c98d416 100644
--- a/platform/linux-generic/include/odp/plat/event_types.h
+++ b/platform/linux-generic/include/odp/plat/event_types.h
@@ -30,7 +30,6 @@  typedef odp_buffer_t odp_event_t;
 
 #define ODP_EVENT_INVALID ODP_BUFFER_INVALID
 
-#define ODP_EVENT_TYPE_INVALID (-1)
 #define ODP_EVENT_BUFFER         1
 #define ODP_EVENT_PACKET         2
 #define ODP_EVENT_TIMEOUT        3