hwloc.h: add an error reporting section describing the common conventions

Refs #578

Signed-off-by: Brice Goglin <Brice.Goglin@inria.fr>

Author: bgoglin

doc/Makefile.am

@@ -253,6 +253,7 @@ pdf_DATA = $(DOX_A4PDF) $(DOX_LETTERPDF)
 # list of dependencies too.
 
 man3_MANS = \
+        $(DOX_MAN_DIR)/man3/hwlocality_api_error_reporting.3 \
         $(DOX_MAN_DIR)/man3/hwlocality_api_version.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_API_VERSION.3 \
         $(DOX_MAN_DIR)/man3/hwloc_get_api_version.3

include/hwloc.h

@@ -77,6 +77,25 @@ extern "C" {
 #endif
 
 
+/** \defgroup hwlocality_api_error_reporting Error reporting in the API
+ * @{
+ * Most functions in the hwloc API return an integer value.
+ * Unless documentated differently, they return 0 on success
+ * and -1 on error.
+ * Functions that return a pointer type return \c NULL on error.
+ *
+ * \p errno will be set to a meaningful value whenever possible.
+ * This includes the usual \c EINVAL when invalid function parameters are passed
+ * or \c ENOMEM when an internal allocation fails.
+ * Some specific \c errno value are also used, for instance for binding
+ * errors as documented in \ref hwlocality_cpubinding.
+ *
+ * Some modules describe return values of their functions
+ * in their introduction, for instance in \ref hwlocality_bitmap.
+ * @}
+ */
+
+
 /** \defgroup hwlocality_api_version API version
  * @{
  */

include/hwloc/bitmap.h

@@ -50,9 +50,10 @@ extern "C" {
  * hwloc_bitmap_free(set);
  * \endcode
  *
- * \note Most functions below return an int that may be negative in case of
- * error. The usual error case would be an internal failure to realloc/extend
+ * \note Most functions below return 0 on success and -1 on error.
+ * The usual error case would be an internal failure to realloc/extend
  * the storage of the bitmap (\p errno would be set to \c ENOMEM).
+ * See also \ref hwlocality_api_error_reporting.
  *
  * \note Several examples of using the bitmap API are available under the
  * doc/examples/ directory in the source tree.