style: init api: documentation clean up

Organized doxygen tags and line feeds for better source code
and doxygen doc readabilibty.

Signed-off-by: Petri Savolainen <petri.savolainen@nokia.com>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 47 insertions, 45 deletions

diff --git a/include/odp/api/init.h b/include/odp/api/init.h
index 01faedc1e..077356730 100644
--- a/include/odp/api/init.h
+++ b/include/odp/api/init.h
@@ -64,8 +64,8 @@ typedef enum odp_log_level {
  * (utilizes function attribute "weak"). If both are defined, the odp_init_t
  * function pointer has priority over the override function.
  *
- * @param[in] level   Log level
- * @param[in] fmt     printf-style message format
+ * @param level   Log level
+ * @param fmt     printf-style message format
  *
  * @return The number of characters logged on success
  * @retval <0 on failure
@@ -99,107 +99,109 @@ typedef int (*odp_log_func_t)(odp_log_level_e level, const char *fmt, ...);
 /** Replaceable abort function */
 typedef void (*odp_abort_func_t)(void) ODP_NORETURN;
 
-/** ODP initialization data.
+/**
+ * ODP initialization data
+ *
  * Data that is required to initialize the ODP API with the
  * application specific data such as specifying a logging callback, the log
  * level etc.
  *
- * @note it is expected that all unassigned members are zero
+ * @note It is expected that all unassigned members are zero
  */
 typedef struct odp_init_t {
 	odp_log_func_t log_fn; /**< Replacement for the default log fn */
 	odp_abort_func_t abort_fn; /**< Replacement for the default abort fn */
 } odp_init_t;
 
-/** ODP platform initialization data.
+/**
+ * ODP platform initialization data
+ *
  * @note ODP API does nothing with this data. It is the underlying
  * implementation that requires it and any data passed here is not portable.
  * It is required that the application takes care of identifying and
  * passing any required platform specific data.
  */
-
 typedef struct odp_platform_init_t {
 } odp_platform_init_t;
 
 
 /**
- * Perform global ODP initialization.
+ * Global ODP initialization
  *
  * This function must be called once before calling any other ODP API
  * functions.
  *
- * @sa odp_term_global()
- * @sa odp_init_local() which is required per thread before use.
- *
- * @param[in] params Those parameters that are interpreted by the ODP API
- * @param[in] platform_params Those parameters that are passed without
- * interpretation by the ODP API to the implementation.
+ * @param params          Those parameters that are interpreted by the ODP API.
+ * @param platform_params Those parameters that are passed without
+ *                        interpretation by the ODP API to the implementation.
  *
  * @retval 0 on success
  * @retval <0 on failure
+ *
+ * @see odp_term_global()
+ * @see odp_init_local() which is required per thread before use.
  */
 int odp_init_global(odp_init_t *params, odp_platform_init_t *platform_params);
 
 /**
- * Terminate ODP session.
+ * Global ODP termination
  *
  * This function is the final ODP call made when terminating
  * an ODP application in a controlled way. It cannot handle exceptional
- * circumstances.
- * In general it calls the API modules terminate functions in the reverse order
- * to that which the module init functions were called during odp_init_global()
+ * circumstances. In general it calls the API modules terminate functions in
+ * the reverse order to that which the module init functions were called
+ * during odp_init_global().
+ *
+ * @retval 0 on success
+ * @retval <0 on failure
  *
  * @note This function should be called by the last ODP thread. To simplify
  * synchronization between threads odp_term_local() indicates by its return
  * value if it was the last thread.
  *
- * @warning The unwinding of HW resources to allow them to be re used without reseting
- * the device is a complex task that the application is expected to coordinate.
- * This api may have  platform dependant implications.
- *
- * @sa odp_init_global()
- * @sa odp_term_local() which must have been called prior to this.
+ * @warning The unwinding of HW resources to allow them to be reused without
+ * reseting the device is a complex task that the application is expected to
+ * coordinate. This api may have platform dependant implications.
  *
- * @retval 0 on success
- * @retval <0 on failure
+ * @see odp_init_global()
+ * @see odp_term_local() which must have been called prior to this.
  */
 int odp_term_global(void);
 
 /**
- * Perform thread local ODP initialization.
- *
- * All threads must call this function before calling
- * any other ODP API functions.
+ * Thread local ODP initialization
  *
- * @sa odp_term_local()
- * @sa odp_init_global() which must have been called prior to this.
+ * All threads must call this function before calling any other ODP API
+ * functions.
  *
  * @retval 0 on success
  * @retval <0 on failure
+ *
+ * @see odp_term_local()
+ * @see odp_init_global() which must have been called prior to this.
  */
 int odp_init_local(void);
 
-
 /**
- * Perform thread local ODP termination.
+ * Thread local ODP termination
  *
  * This function is the second to final ODP call made when terminating
  * an ODP application in a controlled way. It cannot handle exceptional
- * circumstances.
- * In general it calls the API modules per thread terminate functions in the
- * reverse order to that which the module init functions were called during
- * odp_init_local()
- *
- * @sa odp_init_local()
- * @sa odp_term_global() should be called by the last ODP thread before exit
- * of an application.
- *
- * @warning The unwinding of HW resources to allow them to be re used without reseting
- * the device is a complex task that the application is expected to coordinate.
+ * circumstances. In general it calls the API modules per thread terminate
+ * functions in the reverse order to that which the module init functions were
+ * called during odp_init_local().
  *
  * @retval 1 on success and more ODP threads exist
- * @retval 0 on success and it was the last ODP thread
+ * @retval 0 on success and this is the last ODP thread
  * @retval <0 on failure
+ *
+ * @warning The unwinding of HW resources to allow them to be reused without
+ * reseting the device is a complex task that the application is expected
+ * to coordinate.
+ *
+ * @see odp_init_local()
+ * @see odp_term_global() should be called by the last ODP thread before exit
+ * of an application.
  */
 int odp_term_local(void);