Fix minor documentation issues

docs/user-api.rst

@@ -21,8 +21,8 @@ Functions
    :project: libnomp
    :content-only:
 
-Errors
-^^^^^^
-.. doxygengroup:: nomp_user_errors
+Error Codes
+^^^^^^^^^^^
+.. doxygengroup:: nomp_error_codes
    :project: libnomp
    :content-only:

include/nomp-impl.h

@@ -15,6 +15,7 @@
 
 /**
  * @defgroup nomp_internal_types Internal types
+ *
  * @brief Internal types used in libnomp.
  */
 
@@ -256,17 +257,27 @@ typedef struct nomp_backend nomp_backend_t;
 extern "C" {
 #endif
 
+/**
+ * @defgroup nomp_internal_macros Internal macros
+ *
+ * @brief Internal macros used in libnomp.
+ */
+
+/**
+ * @ingroup nomp_internal_macros
+ *
+ * @def NOMP_UNUSED
+ *
+ * @brief Macro to mark unused variables. Used to avoid `-Wunused-variable`
+ * warning. This required since Some backend functions may not use all the
+ * arguments defined in the function signature.
+ */
 #ifdef __GNUC__
 #define NOMP_UNUSED(x) NOMP_UNUSED_##x __attribute__((__unused__))
 #else
 #define NOMP_UNUSED(x) NOMP_UNUSED_##x
 #endif
 
-/**
- * @defgroup nomp_internal_macros Internal macros
- * @brief Internal macros used in libnomp.
- */
-
 /**
  * @ingroup nomp_internal_macros
  *

include/nomp-log.h

@@ -57,9 +57,9 @@ int nomp_log_(const char *desc, int errorno, nomp_log_type_t type, ...);
  * @def nomp_log
  *
  * @brief Log an error, warning or an info message. Use this instead of
- * using the @ref nomp_log_ function directly.
+ * using the nomp_log_() function directly.
  *
- * @param errorno Error number (One of @ref nomp_user_errors. used only when
+ * @param errorno Error number (One of \ref nomp_error_codes. used only when
  * type is an error).
  * @param type Log type one of ::nomp_log_type_t.
  * @param ... Log message as a C-string followed by arguments.

include/nomp.h

@@ -3,6 +3,10 @@
 
 #include <stddef.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * @defgroup nomp_user_types User types
  * @brief Data types used in libnomp user API.
@@ -11,8 +15,9 @@
 /**
  * @ingroup nomp_user_types
  *
- * @brief Defines argument types for a nomp kernel. Currently, only integer,
- * float or pointer types are supported.
+ * @brief Defines argument types supported for a nomp kernel. Used in nomp_jit()
+ * which is used for kernel creation. Currently, only integer, float or pointer
+ * types are supported as kernel arguments.
  */
 typedef enum {
   NOMP_INT = 2048,   /*!< Signed integer argument type.*/
@@ -23,7 +28,7 @@ typedef enum {
 
 /**
  * @ingroup nomp_user_types
- * @brief Defines the update method (or operation) in nomp_update().
+ * @brief Defines the update method (operation) in nomp_update().
  */
 typedef enum {
   NOMP_ALLOC = 1, /*!< Allocate memory on the device.*/
@@ -34,102 +39,124 @@ typedef enum {
 } nomp_map_direction_t;
 
 /**
- * @defgroup nomp_user_errors Error codes returned to the user.
+ * @defgroup nomp_error_codes Error codes returned to the user
  *
- * @brief Error codes returned by libnomp user API calls to the
- * user. These error codes are negative integers.
+ * @brief Error codes used by internal libnomp functions when calling
+ * nomp_log() with ::NOMP_ERROR. User can query these error codes using
+ * nomp_get_err_no() by passing the return value of a libnomp function call
+ * in case of an error. \p NOMP_SUCCESS is used for error code when
+ * nomp_log() is called with ::NOMP_WARNING or ::NOMP_INFO.
  */
 
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
+ * @brief libnomp API call was successful.
+ */
+#define NOMP_SUCCESS 0
+/**
+ * @ingroup nomp_error_codes
+ *
  * @brief One of the inputs to a libnomp function call are not valid.
  */
 #define NOMP_USER_INPUT_IS_INVALID -128
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Map pointer provided to libnomp is not valid.
  */
 #define NOMP_USER_MAP_PTR_IS_INVALID -130
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Map operation provided to libnomp is not applicable.
  */
 #define NOMP_USER_MAP_OP_IS_INVALID -132
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Log id provided to libnomp is not valid.
  */
 #define NOMP_USER_LOG_ID_IS_INVALID -134
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Kernel argument type provided to libnomp is not valid.
  */
 #define NOMP_USER_KNL_ARG_TYPE_IS_INVALID -136
 
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief libnomp is already initialized.
  */
 #define NOMP_INITIALIZE_FAILURE -256
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Failed to finalize libnomp.
  */
 #define NOMP_FINALIZE_FAILURE -258
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief The feature is not implemented.
  */
 #define NOMP_NOT_IMPLEMENTED_ERROR -260
 
 /**
- * @ingroup nomp_user_errors
+ *
+ * @ingroup nomp_error_codes
  * @brief A python call made by libnomp failed.
  */
 #define NOMP_PY_CALL_FAILURE -384
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Loopy conversion failed.
  */
 #define NOMP_LOOPY_CONVERSION_FAILURE -386
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Failed to find loopy kernel.
  */
 #define NOMP_LOOPY_KNL_NAME_NOT_FOUND -388
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Code generation from loopy kernel failed.
  */
 #define NOMP_LOOPY_CODEGEN_FAILURE -390
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief Code generation from loopy kernel failed.
  */
 #define NOMP_LOOPY_GRIDSIZE_FAILURE -392
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief libnomp CUDA operation failed.
  */
 #define NOMP_CUDA_FAILURE -512
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief libnomp HIP failed.
  */
 #define NOMP_HIP_FAILURE -514
 /**
- * @ingroup nomp_user_errors
+ * @ingroup nomp_error_codes
+ *
  * @brief libnomp OpenCL failure.
  */
 #define NOMP_OPENCL_FAILURE -516
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * @defgroup nomp_user_api User API
- * @brief libnomp API functions defined in `nomp.h`.
+ *
+ * @brief libnomp user API functions.
  */
 
 int nomp_init(int argc, const char **argv);

src/aux.c

@@ -128,7 +128,7 @@ char *nomp_copy_env(const char *name, size_t size) {
  * length resolution was successful. Otherwise, it is set to zero. On success,
  * the function returns zero. Otherwise, it returns an error id which can be
  * used to query the error id and string using nomp_get_err_str() and
- * nomp_get_err_id().
+ * nomp_get_err_no().
  *
  * @param[out] len Lenth of path specified in \p path.
  * @param[in] path Path to get the maximum length.

src/log.c

@@ -96,7 +96,7 @@ int nomp_log_(const char *description, int errorno, nomp_log_type_t type, ...) {
  * @details Returns the log of the given error id. Returns NULL if the
  * id is invalid.
  *
- * @param[in] id id of the error log returned by @ref nomp_log.
+ * @param[in] id id of the error log returned by nomp_log().
  * @return char*
  */
 char *nomp_get_err_str(unsigned id) {
@@ -112,9 +112,9 @@ char *nomp_get_err_str(unsigned id) {
  * @brief Return log number given the log id.
  *
  * @details Returns the error number given the id. If id is invalid return
- * NOMP_USER_LOG_ID_IS_INVALID. Error number is one of @ref nomp_user_errors.
+ * NOMP_USER_LOG_ID_IS_INVALID. Error number is one of @ref nomp_error_codes.
  *
- * @param[in] id id of the log returned by @ref nomp_log().
+ * @param[in] id id of the log returned by nomp_log().
  * @return int
  */
 int nomp_get_err_no(unsigned id) {

src/loopy.c

@@ -101,7 +101,7 @@ int nomp_py_append_to_sys_path(const char *path) {
  * Check if there is python function \p function exist in the python module
  * \p module.  Returns 0 if both module and function exist, otherwise returns
  * an error id which can beused to query the error id and string using
- * nomp_get_err_str() and nomp_get_err_id(). The \p module should be provided
+ * nomp_get_err_str() and nomp_get_err_no(). The \p module should be provided
  * without the ".py" extension.
  *
  * @param[in] module Python module name without the ".py" extension.

src/nomp.c

@@ -453,7 +453,7 @@ static inline nomp_prog_t *init_args(int progs_n, int nargs, va_list args) {
  * data can be passed using the \p clauses as well. After \p clauses, number of
  * arguments to the kernel must be provided. Then for each argument, three
  * values has to be passed. First is the argument name as a string. Second is
- * is the `sizeof` argument and the third if argument type (one of @ref
+ * is the `sizeof` argument and the third if argument type (one of \ref
  * nomp_user_types).
  *
  * <b>Example usage:</b>