doc: clarify how we talk about info attributes

Uniformize and clarifies things.
Use "name" instead of "key".
Use "pair" when appropriate.
Misc.

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

Author: bgoglin

doc/hwloc.doxy

@@ -1965,12 +1965,11 @@ See ::hwloc_obj_attr_u for details.
 \section attributes_info Custom string infos
 
 Aside os these generic attribute fields, hwloc annotates
-many objects with string attributes that are made of a key and a
-value.
+many objects with info attributes made of name and value strings.
 Each object contains a list of such pairs that may be consulted
 manually (looking at the object <tt>infos</tt> array field)
 or using the hwloc_obj_get_info_by_name().
-The user may additionally add new key-value pairs to any object using
+The user may additionally add new name-value pairs to any object using
 hwloc_obj_add_info() or the \ref cli_hwloc_annotate program.
 
 Here is a non-exhaustive list of attributes that may be automatically
@@ -2048,7 +2047,7 @@ Unless specified, these info attributes are attached to the root object (Machine
 <dl>
 <dt>Backend (topology root object)</dt>
 <dd>The name of a hwloc backend/component that added objects in the topology.
-If several components were combined, multiple Backend keys may exist,
+If several components were combined, multiple Backend pairs may exist,
 with different values, for instance <tt>x86</tt>, <tt>Linux</tt> and
 <tt>CUDA</tt>.
 </dd>
@@ -3969,13 +3968,13 @@ with <tt>hwloc_topology_set_userdata_export_callback()</tt>
 and <tt>hwloc_topology_set_userdata_import_callback()</tt>.
 
 Each object may also contain some <em>info</em> attributes
-(key name and value) that are setup by hwloc during discovery
+(name and value strings) that are setup by hwloc during discovery
 and that may be extended by the user with
 <tt>hwloc_obj_add_info()</tt> (see also \ref attributes).
 Contrary to the <tt>userdata</tt> field which is unique, multiple info
 attributes may exist for each object, even with the same name.
 These attributes are always exported to XML.
-However, only character strings may be used as key names and values.
+However, only character strings may be used as names and values.
 
 It is also possible to insert Misc objects with a custom name
 anywhere as a leaf of the topology (see \ref miscobjs).
@@ -4060,7 +4059,7 @@ but not in the other.
 
 More changes may obviously be performed by manually modifying the XML export file.
 Simple operations such as modifying object attributes (cache size, memory size
-info keypairs, etc.), moving I/O subtrees, moving Misc objects, or removing
+name-value info attributes, etc.), moving I/O subtrees, moving Misc objects, or removing
 objects are easy to perform.
 
 However, modifying CPU and Memory objects requires care since cpusets and nodesets

include/hwloc.h

@@ -602,7 +602,7 @@ struct hwloc_obj {
                                           * \note Its value must not be changed, hwloc_bitmap_dup() must be used instead.
                                           */
 
-  struct hwloc_info_s *infos;		/**< \brief Array of stringified info type=name. */
+  struct hwloc_info_s *infos;		/**< \brief Array of info attributes (name and value strings). */
   unsigned infos_count;			/**< \brief Size of infos array. */
 
   /* misc */
@@ -687,7 +687,7 @@ union hwloc_obj_attr_u {
   } osdev;
 };
 
-/** \brief Object info
+/** \brief Object info attribute (name and value strings)
  *
  * \sa hwlocality_info_attr
  */
@@ -1121,34 +1121,34 @@ HWLOC_DECLSPEC int hwloc_type_sscanf(const char *string,
 
 
 
-/** \defgroup hwlocality_info_attr Consulting and Adding Key-Value Info Attributes
+/** \defgroup hwlocality_info_attr Consulting and Adding Info Attributes
  *
  * @{
  */
 
-/** \brief Search the given key name in object infos and return the corresponding value.
+/** \brief Search the given name in object infos and return the corresponding value.
  *
- * If multiple keys match the given name, only the first one is returned.
+ * If multiple info attributes match the given name, only the first one is returned.
  *
  * \return A pointer to the value string if it exists.
- * \return \c NULL if no such key exists.
+ * \return \c NULL if no such info attribute exists.
  *
  * \note The string should not be freed by the caller, it belongs to the hwloc library.
  */
 static __hwloc_inline const char *
 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;
 
-/** \brief Add the given info name and value pair to the given object.
+/** \brief Add the given name and value pair to the given object info attributes.
  *
- * The info is appended to the existing info array even if another key
+ * The info pair is appended to the existing info array even if another pair
  * with the same name already exists.
  *
  * The input strings are copied before being added in the object infos.
  *
  * \return \c 0 on success, \c -1 on error.
  *
  * \note This function may be used to enforce object colors in the lstopo
- * graphical output by using "lstopoStyle" as a name and "Background=#rrggbb"
+ * graphical output by adding "lstopoStyle" as a name and "Background=#rrggbb"
  * as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.
  *
  * \note If \p name or \p value contain some non-printable characters, they will
@@ -2666,7 +2666,7 @@ HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t to
  * The \p subtype object attribute may be defined (to a dynamically
  * allocated string) to display something else than "Group" as the
  * type name for this object in lstopo.
- * Custom name/value info pairs may be added with hwloc_obj_add_info() after
+ * Custom name-value info pairs may be added with hwloc_obj_add_info() after
  * insertion.
  *
  * The group \p dont_merge attribute may be set to \c 1 to prevent

utils/hwloc/hwloc-calc.1in

@@ -44,7 +44,7 @@ you should combine invocations:
 \fB\-\-cpukind\fR <n>, \fB\-\-cpukind\fR <infoname>=<infovalue>
 Only keep PUs whose CPU kind match.
 Either a single CPU kind is specified as an index,
-or the info name/value keypair will select matching kinds.
+or the info attribute name-value will select matching kinds.
 
 When specified by index, it corresponds to hwloc ranking of CPU kinds
 which returns energy-efficient cores first, and high-performance