Reviewed-by: Maxim Uvarov <[email protected]>
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 <[email protected]>
---
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.
_______________________________________________
lng-odp mailing list
[email protected]
http://lists.linaro.org/mailman/listinfo/lng-odp
