API: document that insert_group() frees the input object on failure to insert

Refs #619

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

Author: bgoglin

include/hwloc.h

@@ -2793,7 +2793,12 @@ HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t to
  *
  * \return The allocated object on success.
  * \return \c NULL on error.
- */
+ *
+ * \note The only way to free this object is to pass it to hwloc_topology_insert_group_object().
+ * If properly inserted, it will be freed when the entire topology is freed.
+ * If insertion failed (e.g. \c NULL or empty CPU and node-sets),
+ * it is freed before returning the error.
+  */
 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology);
 
 /** \brief Add more structure to the topology by adding an intermediate Group
@@ -2833,6 +2838,8 @@ HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t to
  * hence the existing objects may get reordered (including PUs and NUMA nodes),
  * and their logical indexes may change.
  *
+ * \note If the insertion fails, the input group object is freed.
+ *
  * \return The inserted object if it was properly inserted.
  *
  * \return An existing object if the Group was merged or discarded