docs: fix missing docs for OIIO:attribute() and OIIO::getattribute() (#4987)

Rearrangements in 3.1 dropped the list of recognized attributes from
the visible online docs and failed to document the span varieties. We
fix and also reword a lot of the descriptions for clarity and uniformity.

The previous organization was that there were several varieties of attribute(). In the header, the first one had the overall long explanation, including the list of all the recognized attributes. The other ones had short explanations of how they differed. In the docs, each one was referenced explicitly, pulling in its attendant bit of documentation.

What really happened is that in the header, I made the new span-based version the "flagship" one with the full explanation, but I neglected to reference it in the docs, so the long description disappeared.

I could have fixed by just adding refs to the new functions to the docs, as I originally meant to. But while I was there, I took the opportunity to surround the whole collection with a group marker, and then include the lot of them with a single reference to the group, rather than need to refer to each function variant individually. And while I was at it, I also reworded (and hopefully improved) some of those explanations.

Signed-off-by: Larry Gritz <lg@larrygritz.com>

Author: lgritz

src/doc/imageioapi.rst

@@ -215,49 +215,12 @@ These helper functions are not part of any other OpenImageIO class, they
 just exist in the OpenImageIO namespace as general utilities. (See
 :ref:`sec-pythonmiscapi` for the corresponding Python bindings.)
 
-.. doxygenfunction:: OIIO::attribute(string_view, TypeDesc, const void *)
-
-.. cpp:function:: bool OIIO::attribute(string_view name, int val)
-                  bool OIIO::attribute(string_view name, float val)
-                  bool OIIO::attribute(string_view name, string_view val)
-
-    Shortcuts for setting an attribute to a single int, float, or string.
-
-
-.. doxygenfunction:: OIIO::getattribute(string_view, TypeDesc, void *)
-
-
-.. cpp:function:: bool getattribute (string_view name, int &val)
-                  bool getattribute (string_view name, float &val)
-                  bool getattribute (string_view name, char **val)
-                  bool getattribute (string_view name, std::string& val)
-
-    Specialized versions of `getattribute()` in which the data type is
-    implied by the type of the argument (for single int, float, or string).
-    Two string versions exist: one that retrieves it as a `std::string` and
-    another that retrieves it as a `char *`. In all cases, the return value
-    is `true` if the attribute is found and the requested data type
-    conversion was legal.
-
-    EXAMPLES::
-
-        int threads;
-        OIIO::getattribute ("threads", &threads);
-        std::string path;
-        OIIO::getattribute ("plugin_searchpath", path);
-
-.. cpp:function:: int get_int_attribute (string_view name, int defaultvalue=0)
-                  float get_float_attribute (string_view name, float defaultvalue=0)
-                  string_view get_string_attribute (string_view name, string_view defaultvalue="")
-
-    Specialized versions of `getattribute()` for common types, in which the
-    data is returned directly, and a supplied default value is returned if
-    the attribute was not found.
+.. doxygengroup:: OIIO_attribute
+..
 
-    EXAMPLES::
 
-        int threads = OIIO::get_int_attribute ("threads", 0);
-        string_view path = OIIO::get_string_attribute ("plugin_searchpath");
+.. doxygengroup:: OIIO_getattribute
+..
 
 
 

src/include/OpenImageIO/imageio.h

@@ -3684,18 +3684,28 @@ OIIO_API bool has_error();
 /// error messages.
 OIIO_API std::string geterror(bool clear = true);
 
-/// `OIIO::attribute()` sets a global attribute (i.e., a property or
-/// option) of OpenImageIO. The `name` designates the name of the attribute,
-/// `type` describes the type of data, and `value` is a pointer to memory
-/// containing the new value for the attribute.
+/// @defgroup OIIO_attribute (global OIIO::attribute())
+/// @{
 ///
-/// If the name is known, valid attribute that matches the type specified,
-/// the attribute will be set to the new value and `attribute()` will return
-/// `true`.  If `name` is not recognized, or if the types do not match
-/// (e.g., `type` is `TypeFloat` but the named attribute is a string), the
-/// attribute will not be modified, and `attribute()` will return `false`.
+/// `OIIO::attribute()` sets a global attribute (i.e., a property or option)
+/// of OpenImageIO. The `name` designates the name of the attribute, `value`
+/// is the value to use for the attribute, and for some varieties of the call,
+/// `type` is a TypeDesc describing the data type.
 ///
-/// The following are the recognized attributes:
+/// Most varieties of the call will return `true` if `name` is a known
+/// attribute and its expected type is compatible with the type specified. If
+/// `name` is not recognized, or if the types do not match (e.g., `type` is
+/// `TypeFloat` but the named attribute is supposed to be a string), the
+/// internal attribute will not be modified, and `attribute()` will return
+/// `false`.
+///
+/// In all cases, is up to the caller to ensure that `value` is or refers to
+/// the right kind and size of storage for the given type.
+///
+/// Note that all attributes set by this call may also be retrieved by
+/// `OIIO::getattribute()`.
+///
+/// RECOGNIZED ATTRIBUTES
 ///
 /// - `string options`
 ///
@@ -3914,7 +3924,25 @@ OIIO_API std::string geterror(bool clear = true);
 ///   enable globally in an environment where security is a higher priority
 ///   than being tolerant of partially broken image files.
 ///
-/// @version 3.1
+/// EXAMPLES:
+/// ```
+///     // Setting single simple values simply:
+///     bool ok = OIIO::getattribute("threads", 1);  // implied: int
+///     ok = OIIO::attribute("plugin_searchpath", "/foo/bar:/baz");  // implied: string
+///
+///     // Setting a more complex value using a span, with explicit type
+///     float missing[4] = { 0.0f, 0.0f, 0.0f, 1.0f };
+///     ok = OIIO::attribute("missingcolor", TypeDesc("float[4]"), make_span(missing));
+/// ```
+///
+/// The different varieties of `OIIO::attribute()` call follow:
+
+/// Set the attribute's value from a span (which may be a single value). The
+/// total size of `value` must match the `type` (if not, an assertion will be
+/// thrown for debug builds of OIIO, an error will be printed for release
+/// builds).
+///
+/// @version 3.1+
 template<typename T>
 inline bool attribute(string_view name, TypeDesc type, span<T> value)
 {
@@ -3923,19 +3951,18 @@ inline bool attribute(string_view name, TypeDesc type, span<T> value)
     return attribute(name, type, OIIO::as_bytes(value));
 }
 
-/// A version of `OIIO::attribute()` that takes its value from a span of
-/// untyped bytes. The total size of `value` must match the `type` (if not, an
-/// assertion will be thrown for debug builds of OIIO, an error will be
-/// printed for release builds).
+/// Set the attribute's value from a span of untyped bytes. The total size of
+/// `value` must match the `type` (if not, an assertion will be thrown for
+/// debug builds of OIIO, an error will be printed for release builds).
 ///
-/// @version 3.1
+/// @version 3.1+
 OIIO_API bool attribute(string_view name, TypeDesc type, cspan<std::byte> value);
 
-/// A version of `OIIO::attribute()` where the `value` is only a pointer
-/// specifying the beginning of the memory where the value should be copied
-/// from. This is "unsafe" in the sense that there is no assurance that it
-/// points to a sufficient amount of memory, so the span-based versions of
-/// `attribute()` are preferred.
+/// Set the named attribute to the contents of memory pointed to by `value`,
+/// with the `type` implying the total size to be copied. This is "unsafe" in
+/// the sense that there is no assurance that it points to a sufficient amount
+/// of memory or value type, so the span-based versions of `attribute()` are
+/// preferred.
 ///
 /// This was added in version 2.1.
 OIIO_API bool attribute(string_view name, TypeDesc type, const void* value);
@@ -3954,12 +3981,23 @@ inline bool attribute(string_view name, string_view value) {
     const char *s = valstr.c_str();
     return attribute(name, TypeString, &s);
 }
+/// @}
+
 
-/// Get the named global attribute of OpenImageIO, store it in `value`.
-/// Return `true` if found and it was compatible with the type specified,
-/// otherwise return `false` and do not modify the contents of `value`.  It
-/// is up to the caller to ensure that `val` points to the right kind and
-/// size of storage for the given type.
+/// @defgroup OIIO_getattribute (global OIIO::getattribute())
+/// @{
+///
+/// `OIIO::getattribute()` retrieves a named global attribute of OpenImageIO,
+/// and stores it in `value`. These are the retrieval side of the symmetric
+/// set of `OIIO::attribute()` calls.
+///
+/// Most varieties of the call will return `true` if the named attribute was
+/// found and it was compatible with the type specified, otherwise return
+/// `false` and do not modify the contents of `value`.  In all cases, it is up
+/// to the caller to ensure that `val` points to the right kind and size of
+/// storage for the given type.
+///
+/// RECOGNIZED ATTRIBUTES
 ///
 /// In addition to being able to retrieve all the attributes that are
 /// documented as settable by the `OIIO::attribute()` call, `getattribute()`
@@ -4091,8 +4129,32 @@ inline bool attribute(string_view name, string_view value) {
 ///        IBA::resize                  20   0.24s   (avg  12.18ms)
 ///        IBA::zero                     8   0.66ms  (avg   0.08ms)
 ///
+/// EXAMPLES:
+/// ```
+///     // Retrieving a single simple value with success/failure return:
+///     int threads;
+///     bool ok = OIIO::getattribute("threads", threads);
+///     std::string path;
+///     ok = OIIO::getattribute("plugin_searchpath", path);
 ///
-/// @version 3.1
+///     // Directly returning a single simple value, with default to use
+///     // if the attribute is not found:
+///     int threads = OIIO::get_int_attribute("threads", 0);
+///     string_view path = OIIO::get_string_attribute("plugin_searchpath");
+///
+///     // Returning into a span, with explicit type
+///     float missing[4];
+///     ok = OIIO::getattribute("missingcolor", TypeDesc("float[4]"),
+///                             make_span(missing));
+/// ```
+///
+/// The different varieties of `OIIO::getattribute()` call follow:
+
+/// Store the named attribute's current value into a writable span. The total
+/// size of `value` must match the `type` (if not, an assertion will be thrown
+/// for debug OIIO builds, an error will be printed for release builds).
+///
+/// @version 3.1+
 template<typename T>
 inline bool getattribute(string_view name, TypeDesc type, span<T> value)
 {
@@ -4101,70 +4163,82 @@ inline bool getattribute(string_view name, TypeDesc type, span<T> value)
     return OIIO::v3_1::getattribute(name, type, OIIO::as_writable_bytes(value));
 }
 
-/// A version of `getattribute()` that stores the value in a span of
-/// untyped bytes. The total size of `value` must match the `type` (if
-/// not, an assertion will be thrown for debug OIIO builds, an error will
-/// be printed for release builds).
+/// Store the value in a span of untyped bytes. The total size of `value` must
+/// match the `type` (if not, an assertion will be thrown for debug OIIO
+/// builds, an error will be printed for release builds).
 ///
-/// @version 3.1
+/// @version 3.1+
 OIIO_API bool getattribute(string_view name, TypeDesc type,
                            span<std::byte> value);
 
-/// A version of `OIIO::getattribute()` where the `value` is only a pointer
-/// specifying the beginning of the memory where the value should be copied.
-/// This is "unsafe" in the sense that there is no assurance that it points to
-/// a sufficient amount of memory, so the span-based versions of `attribute()`
-/// are preferred.
+/// Store the value into memory pointed to by `val`. This is "unsafe" in the
+/// sense that there is no assurance that it points to a sufficient amount of
+/// memory or will be interpreted as the correct type, so the span-based
+/// versions of `attribute()` are preferred.
 OIIO_API bool getattribute(string_view name, TypeDesc type, void* val);
 
-/// Shortcut getattribute() for retrieving a single integer. The value is
-/// placed in `value`, and the function returns `true` if the attribute was
-/// found and was legally convertible to an int.
+/// Retrieve a single-integer attribute. The value is placed in `value`, and
+/// the function returns `true` if the attribute was found and was legally
+/// convertible to an int.
 inline bool getattribute (string_view name, int &value) {
     return getattribute (name, TypeInt, &value);
 }
-/// Shortcut getattribute() for retrieving a single float. The value is placed
-/// in `value`, and the function returns `true` if the attribute was found and
-/// was legally convertible to a float.
+
+/// Retrieve a single-float attribute. The value is placed in `value`, and the
+/// function returns `true` if the attribute was found and was legally
+/// convertible to a float.
 inline bool getattribute (string_view name, float &value) {
     return getattribute (name, TypeFloat, &value);
 }
-/// Shortcut getattribute() for retrieving a single string as a `std::string`.
-/// The value is placed in `value`, and the function returns `true` if the
-/// attribute was found.
+
+/// Retrieve a single-string attribute, placed as a `std::string` into
+/// `value`, and the function returns `true` if the attribute was found and
+/// was legally convertible to an string.
 inline bool getattribute (string_view name, std::string &value) {
     ustring s;
     bool ok = getattribute (name, TypeString, &s);
     if (ok)
         value = s.string();
     return ok;
 }
-/// Shortcut getattribute() for retrieving a single string as a `char*`.
-inline bool getattribute (string_view name, char **val) {
-    return getattribute (name, TypeString, val);
+
+/// Retrieve a single-string attribute, placed as a `const char*` into
+/// `*value`, and the function returns `true` if the attribute was found and
+/// was legally convertible to an string. Note that the `const char*`
+/// retrieved is really the characters belonging to a `ustring`, and so is
+/// owned by OIIO and should not be freed by the calling code.
+inline bool getattribute (string_view name, char **value) {
+    return getattribute (name, TypeString, value);
 }
-/// Shortcut getattribute() for retrieving a single integer, with a supplied
-/// default value that will be returned if the attribute is not found or
-/// could not legally be converted to an int.
+
+/// Retrieve a single-integer attribute, with a supplied default value that
+/// will be returned if the attribute is not found or could not legally be
+/// converted to an int.
 inline int get_int_attribute (string_view name, int defaultval=0) {
     int val;
     return getattribute (name, TypeInt, &val) ? val : defaultval;
 }
-/// Shortcut getattribute() for retrieving a single float, with a supplied
-/// default value that will be returned if the attribute is not found or
-/// could not legally be converted to a float.
+
+/// Retrieve a single-float attribute, with a supplied default value that
+/// will be returned if the attribute is not found or could not legally be
+/// converted to a float.
 inline float get_float_attribute (string_view name, float defaultval=0) {
     float val;
     return getattribute (name, TypeFloat, &val) ? val : defaultval;
 }
-/// Shortcut getattribute() for retrieving a single string, with a supplied
-/// default value that will be returned if the attribute is not found.
+
+/// Retrieve a single-string attribute, with a supplied default value that
+/// will be returned if the attribute is not found or could not legally be
+/// converted to an int. default value that will be returned if the attribute
+/// is not found.
 inline string_view get_string_attribute (string_view name,
                                  string_view defaultval = string_view()) {
     ustring val;
     return getattribute (name, TypeString, &val) ? string_view(val) : defaultval;
 }
 
+/// @}
+
 
 /// Set the metadata of the `spec` to presume that color space is `name` (or
 /// to assume nothing about the color space if `name` is empty). The core