hwloc/memattrs.h: improve doc about return values

Refs #578

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

Author: bgoglin

include/hwloc/memattrs.h

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2019-2022 Inria.  All rights reserved.
+ * Copyright © 2019-2023 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -178,6 +178,9 @@ enum hwloc_memattr_id_e {
 typedef unsigned hwloc_memattr_id_t;
 
 /** \brief Return the identifier of the memory attribute with the given name.
+ *
+ * \return 0 on success.
+ * \return -1 with errno set to \c EINVAL if no such attribute exists.
  */
 HWLOC_DECLSPEC int
 hwloc_memattr_get_by_name(hwloc_topology_t topology,
@@ -247,6 +250,8 @@ enum hwloc_local_numanode_flag_e {
  * or the number of nodes that would have been stored if there were
  * enough room.
  *
+ * \return 0 on success or -1 on error.
+ *
  * \note Some of these NUMA nodes may not have any memory attribute
  * values and hence not be reported as actual targets in other functions.
  *
@@ -276,6 +281,10 @@ hwloc_get_local_numanode_objs(hwloc_topology_t topology,
  *
  * \p flags must be \c 0 for now.
  *
+ * \return 0 on success.
+ * \return -1 on error, for instance with errno set to \c EINVAL if flags
+ * are invalid or no such attribute exists.
+ *
  * \note The initiator \p initiator should be of type ::HWLOC_LOCATION_TYPE_CPUSET
  * when refering to accesses performed by CPU cores.
  * ::HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc,
@@ -307,7 +316,10 @@ hwloc_memattr_get_value(hwloc_topology_t topology,
  *
  * \p flags must be \c 0 for now.
  *
- * If there are no matching targets, \c -1 is returned with \p errno set to \c ENOENT;
+ * \return 0 on success.
+ * \return -1 with errno set to \c ENOENT if there are no matching targets.
+ * \return -1 with errno set to \c EINVAL if flags are invalid,
+ * or no such attribute exists.
  *
  * \note The initiator \p initiator should be of type ::HWLOC_LOCATION_TYPE_CPUSET
  * when refering to accesses performed by CPU cores.
@@ -323,10 +335,6 @@ hwloc_memattr_get_best_target(hwloc_topology_t topology,
                               hwloc_obj_t *best_target, hwloc_uint64_t *value);
 
 /** \brief Return the best initiator for the given attribute and target NUMA node.
- *
- * If the attribute does not relate to a specific initiator
- * (it does not have the flag ::HWLOC_MEMATTR_FLAG_NEED_INITIATOR),
- * \c -1 is returned and \p errno is set to \c EINVAL.
  *
  * If \p value is non \c NULL, the corresponding value is returned there.
  *
@@ -342,7 +350,10 @@ hwloc_memattr_get_best_target(hwloc_topology_t topology,
  *
  * \p flags must be \c 0 for now.
  *
- * If there are no matching initiators, \c -1 is returned with \p errno set to \c ENOENT;
+ * \return 0 on success.
+ * \return -1 with errno set to \c ENOENT if there are no matching initiators.
+ * \return -1 with errno set to \c EINVAL if the attribute does not relate to a specific initiator
+ * (it does not have the flag ::HWLOC_MEMATTR_FLAG_NEED_INITIATOR).
  */
 HWLOC_DECLSPEC int
 hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
@@ -359,6 +370,9 @@ hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
  */
 
 /** \brief Return the name of a memory attribute.
+ *
+ * \return 0 on success.
+ * \return -1 with errno set to \c EINVAL if the attribute does not exist.
  */
 HWLOC_DECLSPEC int
 hwloc_memattr_get_name(hwloc_topology_t topology,
@@ -368,6 +382,9 @@ hwloc_memattr_get_name(hwloc_topology_t topology,
 /** \brief Return the flags of the given attribute.
  *
  * Flags are a OR'ed set of ::hwloc_memattr_flag_e.
+ *
+ * \return 0 on success.
+ * \return -1 with errno set to \c EINVAL if the attribute does not exist.
  */
 HWLOC_DECLSPEC int
 hwloc_memattr_get_flags(hwloc_topology_t topology,
@@ -397,6 +414,9 @@ enum hwloc_memattr_flag_e {
  * Add a specific memory attribute that is not defined in ::hwloc_memattr_id_e.
  * Flags are a OR'ed set of ::hwloc_memattr_flag_e. It must contain at least
  * one of ::HWLOC_MEMATTR_FLAG_HIGHER_FIRST or ::HWLOC_MEMATTR_FLAG_LOWER_FIRST.
+ *
+ * \return 0 on success.
+ * \return -1 with errno set to \c EBUSY if another attribute already uses this name.
  */
 HWLOC_DECLSPEC int
 hwloc_memattr_register(hwloc_topology_t topology,
@@ -421,6 +441,8 @@ hwloc_memattr_register(hwloc_topology_t topology,
  * ::HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc,
  * but users may for instance use it to provide custom information about
  * host memory accesses performed by GPUs.
+ *
+ * \return 0 on success or -1 on error.
  */
 HWLOC_DECLSPEC int
 hwloc_memattr_set_value(hwloc_topology_t topology,
@@ -460,6 +482,8 @@ hwloc_memattr_set_value(hwloc_topology_t topology,
  * NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute
  * values.
  *
+ * \return 0 on success or -1 on error.
+ *
  * \note The initiator \p initiator should be of type ::HWLOC_LOCATION_TYPE_CPUSET
  * when referring to accesses performed by CPU cores.
  * ::HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc,
@@ -497,6 +521,8 @@ hwloc_memattr_get_targets(hwloc_topology_t topology,
  * (it does not have the flag ::HWLOC_MEMATTR_FLAG_NEED_INITIATOR),
  * no initiator is returned.
  *
+ * \return 0 on success or -1 on error.
+ *
  * \note This function is meant for tools and debugging (listing internal information)
  * rather than for application queries. Applications should rather select useful
  * NUMA nodes with hwloc_get_local_numanode_objs() and then look at their attribute