hwloc/distances.h: add/improve doc about return values

Refs #578

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

Author: bgoglin

include/hwloc/distances.h

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2010-2022 Inria.  All rights reserved.
+ * Copyright © 2010-2023 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -131,6 +131,8 @@ enum hwloc_distances_kind_e {
  *
  * Each distance matrix returned in the \p distances array should be released
  * by the caller using hwloc_distances_release().
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int
 hwloc_distances_get(hwloc_topology_t topology,
@@ -140,6 +142,8 @@ hwloc_distances_get(hwloc_topology_t topology,
 /** \brief Retrieve distance matrices for object at a specific depth in the topology.
  *
  * Identical to hwloc_distances_get() with the additional \p depth filter.
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int
 hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth,
@@ -149,6 +153,8 @@ hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth,
 /** \brief Retrieve distance matrices for object of a specific type.
  *
  * Identical to hwloc_distances_get() with the additional \p type filter.
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int
 hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type,
@@ -162,6 +168,8 @@ hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type,
  * The name of the most common structure is "NUMALatency".
  * Others include "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth",
  * and "NVLinkBandwidth".
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int
 hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
@@ -171,7 +179,12 @@ hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
 /** \brief Get a description of what a distances structure contains.
  *
  * For instance "NUMALatency" for hardware-provided NUMA distances (ACPI SLIT),
- * or NULL if unknown.
+ * or \c NULL if unknown.
+ *
+ * \return the constant string with the name of the distance structure.
+ *
+ * \note The returned name should not be freed by the caller,
+ * it belongs to the hwloc library.
  */
 HWLOC_DECLSPEC const char *
 hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances);
@@ -252,6 +265,8 @@ enum hwloc_distances_transform_e {
  *
  * \p flags must be \c 0 for now.
  *
+ * \return 0 on success, -1 on error for instance if flags are invalid.
+ *
  * \note Objects in distances array \p objs may be directly modified
  * in place without using hwloc_distances_transform().
  * One may use hwloc_get_obj_with_same_locality() to easily convert
@@ -272,6 +287,7 @@ HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct h
 
 /** \brief Find the index of an object in a distances structure.
  *
+ * \return the index of the object in the distances structure if any.
  * \return -1 if object \p obj is not involved in structure \p distances.
  */
 static __hwloc_inline int
@@ -289,6 +305,7 @@ hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
  * The distance from \p obj1 to \p obj2 is stored in the value pointed by
  * \p value1to2 and reciprocally.
  *
+ * \return 0 on success.
  * \return -1 if object \p obj1 or \p obj2 is not involved in structure \p distances.
  */
 static __hwloc_inline int
@@ -374,8 +391,8 @@ hwloc_distances_add_create(hwloc_topology_t topology,
  *
  * \p flags must be \c 0 for now.
  *
- * \return \c 0 on success.
- * \return \c -1 on error.
+ * \return 0 on success.
+ * \return -1 on error.
  */
 HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
                                               hwloc_distances_add_handle_t handle,
@@ -411,8 +428,8 @@ enum hwloc_distances_add_flag_e {
  *
  * On error, the temporary distances structure and its content are destroyed.
  *
- * \return \c 0 on success.
- * \return \c -1 on error.
+ * \return 0 on success.
+ * \return -1 on error.
  */
 HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
                                               hwloc_distances_add_handle_t handle,
@@ -433,18 +450,24 @@ HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
  *
  * If these distances were used to group objects, these additional
  * Group objects are not removed from the topology.
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
 
 /** \brief Remove distance matrices for objects at a specific depth in the topology.
  *
  * Identical to hwloc_distances_remove() but only applies to one level of the topology.
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
 
 /** \brief Remove distance matrices for objects of a specific type in the topology.
  *
  * Identical to hwloc_distances_remove() but only applies to one level of the topology.
+ *
+ * \return 0 on success, -1 on error.
  */
 static __hwloc_inline int
 hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
@@ -458,6 +481,8 @@ hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
 /** \brief Release and remove the given distance matrice from the topology.
  *
  * This function includes a call to hwloc_distances_release().
+ *
+ * \return 0 on success, -1 on error.
  */
 HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);