| Message ID | 1417025148-21535-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Not Applicable |
| Headers | show |
Reviewed-by: Maxim Uvarov <maxim.uvarov@linaro.org> Maxim. On 11/26/2014 09:05 PM, Mike Holmes wrote: > The API require guide lines to help it conform to a consistent look and feel. > These additional clarifications help promote those guidelines. > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > api_guide_lines.dox | 30 +++++++++++++++++++++++++----- > 1 file changed, 25 insertions(+), 5 deletions(-) > > diff --git a/api_guide_lines.dox b/api_guide_lines.dox > index 4903961..be23e9a 100644 > --- a/api_guide_lines.dox > +++ b/api_guide_lines.dox > @@ -48,7 +48,7 @@ type | Correct use > |---| :--------- > void | SHOULD be used for APIs that do not return a value > void*| SHOULD be used for APIs that return a pointer intended to be used by the caller. For example, a routine that returns the address of an application context area SHOULD use a void * return type > -int | SHOULD be used for APIs that return a boolean value. The values 1 = true, 0 = false are used for this purpose > +odp_bool_t | SHOULD be used for APIs that return a @ref boolean value. > int | SHOULD be used for success and failure indications, with 0 indicating a success. Errno may be set > > @subsection parameters Parameter Structure and Validation > @@ -79,6 +79,27 @@ Other mechanisms available to the implementer are: > - ODP_LOG() is used to direct implementation messages to the application. > > > +@subsection function_name Function Names > +Functions must attempt to be so clear in their intent that referencing the documentation is not necessary, the guidelines below should be followed unless a strong case is made for an exception. > + > +@subsection getters Getting information > + > +@subsubsection is_has Is / Has > +An api with "is" or "has" are both considered @ref boolean questions. They can only return true or false and it reflects the current state of something. > + > +An example might be a packet interface, you might want to know if it is in promiscuous mode. > +@code odp_bool_t state = odp_pktio_is_promiscuous(pktio handle) @endcode > + > +In addtion you might want to know if it has the ability to be in promiscuous mode. > +@code odp_bool_t state = odp_pktio_has_promiscuous(pktio handle) @endcode > + > +Another case might be if a packet has a vlan flag set > +@code odp_bool_t state = odp_packet_has_vlan(packet handle) @endcode > + > +@subsubsection get Get > +Where possible returned information should be an enum if it reflects a finite list of information. > +In general get apis drop the actual tag "get" in the function name. > + > @subsection function_calls Function Calls > ODP APIs typically have prototypes of the form: > > @@ -95,7 +116,7 @@ p2_type | Is the data type of the second parameter, etc. > > For ODP APIs that return void, results are undefined if the input parameters are invalid. > For those that return void *, the value ODP_NULL or ODP_INVALID MAY be used to indicate call failure. > -For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure. > +For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure see @ref success. > > @subsection errno Use of errno > ODP APIs SHOULD make use of the thread-local variable errno, defined in the standard library include file errno.h, to indicate a reason for an API call failure when appropriate. > @@ -116,14 +137,13 @@ An example of this might be the number of queues that an application can create. > An attempt to allocate more queues than the underlying implementation supports would result in this failure code being returned via errno. > > @subsection boolean Boolean > -For odp booleans are integers (int) > -The values 1 = true, 0 = false are used for this purpose. > +For odp all booleans are integers. To aid application readability they are defined as the type odp_bool_t. > +The values !0 = true, 0 = false are used for this purpose. > > @subsection success Success and Failure > Pass indications are integers (int) and SHOULD also be used for APIs that return a simple success/failure indication to the caller. > In this case the return value 0 indicates success while non-zero (typically -1) indicates failure and errno is set to a reason code that indicates the nature of the failure. > > - > @section implementation Implementation Considerations > To support application portability and preserve implementation flexibility, ODP APIs MUST be designed with several guiding principles in mind. >
On 2014-11-26 13:05, Mike Holmes wrote: > The API require guide lines to help it conform to a consistent look and feel. > These additional clarifications help promote those guidelines. > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- Applied!
diff --git a/api_guide_lines.dox b/api_guide_lines.dox index 4903961..be23e9a 100644 --- a/api_guide_lines.dox +++ b/api_guide_lines.dox @@ -48,7 +48,7 @@ type | Correct use |---| :--------- void | SHOULD be used for APIs that do not return a value void*| SHOULD be used for APIs that return a pointer intended to be used by the caller. For example, a routine that returns the address of an application context area SHOULD use a void * return type -int | SHOULD be used for APIs that return a boolean value. The values 1 = true, 0 = false are used for this purpose +odp_bool_t | SHOULD be used for APIs that return a @ref boolean value. int | SHOULD be used for success and failure indications, with 0 indicating a success. Errno may be set @subsection parameters Parameter Structure and Validation @@ -79,6 +79,27 @@ Other mechanisms available to the implementer are: - ODP_LOG() is used to direct implementation messages to the application. +@subsection function_name Function Names +Functions must attempt to be so clear in their intent that referencing the documentation is not necessary, the guidelines below should be followed unless a strong case is made for an exception. + +@subsection getters Getting information + +@subsubsection is_has Is / Has +An api with "is" or "has" are both considered @ref boolean questions. They can only return true or false and it reflects the current state of something. + +An example might be a packet interface, you might want to know if it is in promiscuous mode. +@code odp_bool_t state = odp_pktio_is_promiscuous(pktio handle) @endcode + +In addtion you might want to know if it has the ability to be in promiscuous mode. +@code odp_bool_t state = odp_pktio_has_promiscuous(pktio handle) @endcode + +Another case might be if a packet has a vlan flag set +@code odp_bool_t state = odp_packet_has_vlan(packet handle) @endcode + +@subsubsection get Get +Where possible returned information should be an enum if it reflects a finite list of information. +In general get apis drop the actual tag "get" in the function name. + @subsection function_calls Function Calls ODP APIs typically have prototypes of the form: @@ -95,7 +116,7 @@ p2_type | Is the data type of the second parameter, etc. For ODP APIs that return void, results are undefined if the input parameters are invalid. For those that return void *, the value ODP_NULL or ODP_INVALID MAY be used to indicate call failure. -For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure. +For non-boolean APIs returning int, a return value of 0 indicates success while non-zero indicates failure see @ref success. @subsection errno Use of errno ODP APIs SHOULD make use of the thread-local variable errno, defined in the standard library include file errno.h, to indicate a reason for an API call failure when appropriate. @@ -116,14 +137,13 @@ An example of this might be the number of queues that an application can create. An attempt to allocate more queues than the underlying implementation supports would result in this failure code being returned via errno. @subsection boolean Boolean -For odp booleans are integers (int) -The values 1 = true, 0 = false are used for this purpose. +For odp all booleans are integers. To aid application readability they are defined as the type odp_bool_t. +The values !0 = true, 0 = false are used for this purpose. @subsection success Success and Failure Pass indications are integers (int) and SHOULD also be used for APIs that return a simple success/failure indication to the caller. In this case the return value 0 indicates success while non-zero (typically -1) indicates failure and errno is set to a reason code that indicates the nature of the failure. - @section implementation Implementation Considerations To support application portability and preserve implementation flexibility, ODP APIs MUST be designed with several guiding principles in mind.
The API require guide lines to help it conform to a consistent look and feel. These additional clarifications help promote those guidelines. Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- api_guide_lines.dox | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-)