distances: clarify that distances must have one FROM and one MEANS kind

MEANS might need to be relaxed, but that's what's implemented right now.

Signed-off-by: Brice Goglin <[email protected]>

Author: bgoglin

include/hwloc/distances.h

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2010-2023 Inria.  All rights reserved.
+ * Copyright © 2010-2024 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -70,11 +70,10 @@ struct hwloc_distances_s {
  * The \p kind attribute of struct hwloc_distances_s is a OR'ed set
  * of kinds.
  *
- * A kind of format HWLOC_DISTANCES_KIND_FROM_* specifies where the
- * distance information comes from, if known.
- *
- * A kind of format HWLOC_DISTANCES_KIND_MEANS_* specifies whether
- * values are latencies or bandwidths, if applicable.
+ * Each distance matrix has exactly one kind HWLOC_DISTANCES_KIND_FROM_*
+ * specifying where distance information comes from,
+ * and exactly one kind HWLOC_DISTANCES_KIND_MEANS_* specifying
+ * whether values are latencies or bandwidths.
  */
 enum hwloc_distances_kind_e {
   /** \brief These distances were obtained from the operating system or hardware.
@@ -357,6 +356,8 @@ typedef void * hwloc_distances_add_handle_t;
  * Otherwise, it will be copied internally and may later be freed by the caller.
  *
  * \p kind specifies the kind of distance as a OR'ed set of ::hwloc_distances_kind_e.
+ * Exactly one kind of meaning and one kind of provenance must be given
+ * (e.g. ::HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH and ::HWLOC_DISTANCES_KIND_FROM_USER).
  * Kind ::HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES will be automatically set
  * according to objects having different types in hwloc_distances_add_values().
  *