[#282]:svarga:docs, decorate H5A public surface + add bracket-syntax read/write for gr_t/ob_t

Worked example for the alias-first docstring vocabulary across the
full H5A entry-point surface (h5::create attribute overload,
h5::open, h5::aread, h5::awrite, h5::adelete), plus a symmetric
bracket-syntax read/write API extending the existing ds_t["x"] = v
idiom to gr_t and ob_t and adding implicit-conversion read.

DOCSTRINGS

* H5Acreate.hpp / H5Aopen.hpp / H5Aread.hpp / H5Awrite.hpp /
  H5Adelete.hpp -- each public entry point gets the standard
  alias-first docstring template:
    - \func_attr_hdr (resolves to @InGroup attribute-io)
    - \tpar_T for element-type template parameter
    - \par_args_attr for variadic context-sensitive optionals
      (h5::current_dims, h5::acpl_t) -- attribute-specific surface,
      not the dataset \par_args
    - \par_current_dims where relevant
    - explicit @param for parent (notes ::hid_t / gr_t / ds_t / ob_t /
      dt_t<T>; h5::fd_t needs explicit static_cast<::hid_t>(fd))
    - @return spelling out h5::at_t RAII handle + H5Aclose lifecycle
    - @throws for the leaf exception types
    - @code example block showing the function in context
    - \sa_h5cpp / \sa_hdf5 cross-reference bundles
* Examples across the three primary ops (create / awrite / aread)
  share the same schema_version / spacing / label triple so a reader
  can follow the round-trip; each example is verbatim-compilable.

SFINAE-RETURN-TYPE MACROS

* One per entry point, gated on H5CPP_DOXYGEN:
  - H5CPP_ATTR_CREATE_RET (existing)
  - H5CPP_ATTR_OPEN_RET / H5CPP_ATTR_DELETE_RET / H5CPP_ATTR_READ_RET /
    H5CPP_ATTR_WRITE_RET
  Real compile resolves through std::enable_if_t / attr_parent_t;
  Doxygen pass collapses to the advertised return type so the
  rendered signature reads as plain h5::at_t / void / T instead of
  leaking the SFINAE machinery into the headline.
* doxy/Doxyfile EXPAND_AS_DEFINED += each macro.

TEMPLATE PARAMETER RENAME

* HID_T / P template parameter renamed to lowercase hid_t across
  every overload for symmetry with the rendered signature
  presentation (matches the user's earlier preference on H5Acreate).
* All in-body uses of the HDF5 typedef are now qualified as
  ::hid_t to disambiguate from the shadowed template parameter
  (38 sites in H5Aread.hpp, ~60 sites in H5Awrite.hpp).

BRACKET-SYNTAX API (gr_t["x"] / ob_t["x"] + symmetric implicit read)

* H5Iall.hpp:
  - operator[](const char[]) declarations added to the hdf5::any
    spec (covers ob_t) and the hdf5::attribute spec (covers gr_t).
    The existing declaration on the hdf5::dataset spec stays for
    ds_t. Doxygen-visible docstrings on each.
  - Symmetric implicit read declaration added to the attribute spec:
        template <class V,
            class = std::enable_if_t<!std::is_same_v<V, ::hid_t>>>
        operator V() const;
    SFINAE excludes ::hid_t so static_cast<::hid_t> on the handle
    itself still resolves to the inherited base-spec accessor.
* H5Awrite.hpp:
  - operator[] specializations for h5::gr_t and h5::ob_t mirroring
    the existing h5::ds_t body (open if H5Aexists, otherwise UNINIT
    at_t with ds + name fields populated).
* H5Aread.hpp:
  - Implementation of h5::at_t::operator V() const forwards to
    h5::aread<V>(this->ds, this->name) using the raw ::hid_t
    directly. Crucial: does NOT wrap in h5::ob_t{this->ds} -- doing
    so would close the underlying handle when the temporary
    destructs and orphan the caller's parent (caught by end-to-end
    test, see commit history).

UMBRELLA HEADER FIX

* h5cpp/io: added missing #include "H5Adelete.hpp". Pre-existing
  bug -- adelete was reachable only via direct header include, not
  through the public h5cpp/all umbrella.

DOCS

* doxy/anchors.dox -- new handle_ref_indexer subsection on the
  Handle Reference page describing the bracket syntax, the at_t-as-
  intermediate model, the read-T-from-LHS pattern, and the caveats
  (auto deduces at_t, not the value; parent lifetime must outlive
  the conversion).

VERIFICATION

* End-to-end compile + run on each docstring example individually
  and on the bracket-syntax round-trip (write 4 attrs through
  gr_t[]/ob_t[]/explicit awrite, read 4 back through implicit
  conversion + explicit aread, h5dump confirms all expected
  on-disk dtypes and shapes).
* Doxygen build clean -- no warnings touching H5A files or H5Iall.

Author: steven-varga

doxy/Doxyfile

@@ -168,3 +168,7 @@ MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 PREDEFINED            += H5CPP_DOXYGEN=1
 EXPAND_AS_DEFINED     += H5CPP_ATTR_CREATE_RET
+EXPAND_AS_DEFINED     += H5CPP_ATTR_OPEN_RET
+EXPAND_AS_DEFINED     += H5CPP_ATTR_DELETE_RET
+EXPAND_AS_DEFINED     += H5CPP_ATTR_READ_RET
+EXPAND_AS_DEFINED     += H5CPP_ATTR_WRITE_RET

doxy/anchors.dox

@@ -554,6 +554,41 @@
  *   <tr><td>`h5::dt_t<T>` (template)</td><td>`H5Tclose`</td><td>datatype for `T`</td>      <td>default-constructed: `h5::dt_t<int>{}` looks up the cached HDF5 type for `T`</td></tr>
  * </table>
  *
+ * @subsection handle_ref_indexer Attribute bracket syntax
+ *
+ * `h5::ds_t`, `h5::gr_t`, and `h5::ob_t` expose an `operator[](const char*)`
+ * that returns a transient `h5::at_t` carrying the parent handle and the
+ * attribute name. Combined with `at_t::operator=(V)` and the templated
+ * `at_t::operator V() const`, this gives a symmetric Python-dict-like API
+ * for attribute I/O without leaving expression syntax:
+ *
+ * @code
+ * h5::gr_t gr = h5::gopen(fd, "/grid");
+ *
+ * // write
+ * gr["title"]   = std::string{"hello"};
+ * gr["count"]   = 42;
+ * gr["values"]  = std::vector<double>{1.0, 2.0, 3.0};
+ *
+ * // read — implicit conversion picks T from the left-hand side
+ * std::string title  = gr["title"];
+ * int         count  = gr["count"];
+ * @endcode
+ *
+ * The bracket form is sugar over the free-function surface; both write the
+ * same on-disk bytes as `h5::awrite(gr, "title", ...)` and read the same
+ * value as `h5::aread<T>(gr, "title")`. Type `V` follows the same dispatch
+ * matrix as the rest of the I/O API (see @ref link_base_template_types
+ * "Supported Types"). The conversion excludes `::hid_t` so plain
+ * `static_cast<::hid_t>(at_t)` still resolves to the inherited handle accessor.
+ *
+ * Caveats:
+ *   - `auto v = gr["x"]` deduces `at_t`, **not** the attribute value; the
+ *     implicit conversion needs a concrete LHS type to fire.
+ *   - The transient `at_t` only carries `ds` + `name`; if the parent handle
+ *     is closed before the conversion runs, the read throws
+ *     `h5::error::io::attribute::read`.
+ *
  * @section handle_ref_async Async-mode handles
  *
  * Specialisations with both conversion directions deleted at the type

h5cpp/H5Acreate.hpp

@@ -10,38 +10,111 @@
 #include "H5Sall.hpp"
 #include "H5capi.hpp"
 
+// Return-type macro for h5::create<T>(parent, path, ...).
+// Real compile: the SFINAE-constrained h5::impl::attr_parent_t<hid_t>
+//   alias — only parents that can carry attributes (file, group,
+//   dataset, opaque object, committed datatype) participate in overload
+//   resolution.
+// Doxygen   : collapses to plain h5::at_t so the rendered signature
+//   reads cleanly without leaking the std::enable_if_t<...> machinery
+//   into the headline. Gated on H5CPP_DOXYGEN from doxy/Doxyfile.
+#ifdef H5CPP_DOXYGEN
+#  define H5CPP_ATTR_CREATE_RET(hid_t) h5::at_t
+#else
+#  define H5CPP_ATTR_CREATE_RET(hid_t) h5::impl::attr_parent_t<hid_t>
+#endif
 
 namespace h5 {
 	namespace impl {
-		/*this template defines what HDF5 object types may have attributes */
 		template <class H, class T=void> using is_valid_attr =
 			std::bool_constant<std::is_same_v<H, ::hid_t> ||
 				std::is_same_v<H, h5::gr_t> || std::is_same_v<H, h5::ds_t> ||
 				std::is_same_v<H, h5::ob_t> || std::is_same_v<H, h5::dt_t<T>>>;
 		/*template <class H, class T=void> using is_valid_attr =
 			std::bool_constant<std::is_same_v<H, h5::ds_t>>;*/
+
+		template <class hid_t>
+		using attr_parent_t = std::enable_if_t<is_valid_attr<hid_t>::value, h5::at_t>;
 	}
 
-	template<class T, class HID_T, class... args_t> 
-	inline std::enable_if_t<h5::impl::is_valid_attr<HID_T>::value,
-	h5::at_t> create( const HID_T& parent, const std::string& path, args_t&&... args ){
+	/**
+	 * \func_attr_hdr
+	 * @brief Create a new attribute of element type `T` on a parent HDF5 object.
+	 *
+	 * Attributes are small named metadata items attached to a parent object (file, group, dataset, opaque object, or committed datatype).
+	 * `h5::create` allocates the on-disk slot — the value itself is later  deposited with `h5::awrite(parent, path, value)` or read back with
+	 * `h5::aread<T>(parent, path)`. The element type `T` follows the same dispatch as the dataset API (see @ref link_base_template_types
+	 * "Supported Types"): elementary scalar, registered compound, fixed or variable-length string, etc. Attributes do not chunk and do not
+	 * support partial I/O, so neither `h5::chunk{}` nor offset/stride/count  apply here.
+	 *
+	 * @param parent    open parent handle: raw `::hid_t`, `h5::gr_t`, `h5::ds_t`, `h5::ob_t`, or `h5::dt_t<T>` — enforced at compile
+	 *                  time via `h5::impl::is_valid_attr`. Note: typed `h5::fd_t` is **not** accepted directly; pass `static_cast<::hid_t>(fd)`
+	 *                  to attach an attribute to the file root. 
+	 * @param path      attribute name (UTF-8); resolved relative to `parent`.
+	 * \par_args_attr
+	 * \tpar_T
+	 * @tparam hid_t    deduced from the `parent` argument; must satisfy `h5::impl::is_valid_attr<hid_t>::value`.
+	 * @return `h5::at_t` RAII handle owning the new attribute id; closes
+	 *         automatically via `H5Aclose` on scope exit. Throws on failure.
+	 *
+	 * The optional arguments are context-sensitive and may be passed in  any order. By default the attribute is created with an empty
+	 * (rank-0) shape and the default attribute creation property list:
+	 *
+	 * \par_current_dims
+	 * Defaults to `{0}` — a scalar attribute. Pass a non-trivial extent for an array-valued attribute (e.g. `h5::current_dims{8}` for an
+	 * 8-element vector attribute).
+	 *
+	 * @param acpl  attribute creation property list (`h5::acpl_t`); defaults to `H5P_ATTRIBUTE_CREATE`.
+	 *
+	 * @throws h5::error::io::attribute::create   on `H5Acreate2` failure (parent does not exist, attribute already exists, type
+	 *         conversion error, etc.).
+	 * @throws h5::error::property_list::misc     when an invalid acpl is supplied.
+	 *
+	 * <br/><b>example:</b> explicit pre-allocation — useful when the shape
+	 * is non-default or you want the attribute slot to exist before any
+	 * value is written. Most call sites skip `h5::create<T>` and let
+	 * `h5::awrite` create-on-demand instead.
+	 * @code
+	 * h5::fd_t fd = h5::open("file.h5", H5F_ACC_RDWR);
+	 * h5::ds_t ds = h5::open(fd, "/grid/data");
+	 *
+	 * // rank-1 of 3 floats; deposit the value later with h5::awrite.
+	 * h5::create<float>(ds, "spacing", h5::current_dims{3});
+	 *
+	 * // Scalar attribute on the file root — fd_t needs an explicit cast
+	 * // (h5::fd_t is not in is_valid_attr; raw ::hid_t is).
+	 * h5::create<double>(static_cast<::hid_t>(fd), "schema_version");
+	 *
+	 * // Round-trip with h5::awrite / h5::aread:
+	 * h5::awrite(ds, "spacing", std::vector<float>{0.5f, 0.5f, 1.0f});
+	 * auto v = h5::aread<std::vector<float>>(ds, "spacing");
+	 * @endcode
+	 *
+	 * \sa_h5cpp
+	 * \sa_hdf5
+	 * @sa h5::aread h5::awrite @ref link_handle_reference
+	 *     "Handles, Descriptors, and Property Lists"
+	 */
+	template<class T, class hid_t, class... args_t>
+	inline H5CPP_ATTR_CREATE_RET(hid_t)
+	create( const hid_t& parent, const std::string& path, args_t&&... args ){
 		try {
 			h5::acpl_t default_acpl{ H5Pcreate(H5P_ATTRIBUTE_CREATE) };
 			const h5::acpl_t& acpl = arg::get(default_acpl, args...);
 
 			H5CPP_CHECK_PROP( acpl, h5::error::property_list::misc, "invalid attribute create property" );
 
 			// and dimensions
-			h5::current_dims_t current_dims_default{0}; // if no current dims_present 
+			h5::current_dims_t current_dims_default{0}; // if no current dims_present
 			// this mutable value will be referenced
 			const h5::current_dims_t& current_dims = arg::get(current_dims_default, args...);
 			// no partial IO or chunks
 			h5::sp_t space = h5::create_simple( current_dims );
 			using element_t = typename meta::decay<T>::type;
 			h5::dt_t<element_t> type;
-			hid_t id = H5I_UNINIT;
-			H5CPP_CHECK_NZ( (id = H5Acreate2( static_cast<hid_t>( parent ), path.c_str(),
-					static_cast<hid_t>(type), static_cast<hid_t>( space ), static_cast<hid_t>( acpl ), H5P_DEFAULT )),
+			::hid_t id = H5I_UNINIT;
+			H5CPP_CHECK_NZ( (id = H5Acreate2( static_cast<::hid_t>( parent ), path.c_str(),
+					static_cast<::hid_t>(type), static_cast<::hid_t>( space ), static_cast<::hid_t>( acpl ), H5P_DEFAULT )),
 					h5::error::io::attribute::create, "couldn't create attribute");
 			return h5::at_t{id};
 		} catch( const std::runtime_error& err ) {

h5cpp/H5Adelete.hpp

@@ -7,13 +7,47 @@
 #include <string>
 #include <type_traits>
 
+// Return-type macro for h5::adelete(parent, name). See H5Acreate.hpp.
+#ifdef H5CPP_DOXYGEN
+#  define H5CPP_ATTR_DELETE_RET(hid_t) void
+#else
+#  define H5CPP_ATTR_DELETE_RET(hid_t) std::enable_if_t<h5::impl::is_valid_attr<hid_t>::value, void>
+#endif
+
 namespace h5 {
-    // Delete an attribute from an HDF5 object by name
-    template<class HID_T>
-    inline std::enable_if_t<h5::impl::is_valid_attr<HID_T>::value, void>
-    adelete(const HID_T& parent, const std::string& name) {
+    /**
+     * \func_attr_hdr
+     * @brief Delete an attribute by name from a parent HDF5 object.
+     *
+     * Removes the named attribute from the on-disk representation of
+     * `parent`. The operation is final — there is no rollback once
+     * `H5Adelete` has succeeded.
+     *
+     * @param parent  open parent handle: raw `::hid_t`, `h5::gr_t`, `h5::ds_t`, `h5::ob_t`, or `h5::dt_t<T>` — enforced at compile
+     *                time via `h5::impl::is_valid_attr`. Typed `h5::fd_t` is **not** accepted directly; pass `static_cast<::hid_t>(fd)`.
+     * @param name    attribute name (UTF-8); resolved relative to `parent`.
+     *
+     * @tparam hid_t  deduced from the `parent` argument; must satisfy `h5::impl::is_valid_attr<hid_t>::value`.
+     * @return void — failures are reported by throwing.
+     *
+     * @throws h5::error::io::attribute::delete_  on `H5Adelete` failure (attribute does not exist, parent invalid, write access denied).
+     *
+     * <br/><b>example:</b>
+     * @code
+     * h5::ds_t ds = h5::open(fd, "/grid/data");
+     * h5::adelete(ds, "stale_marker");
+     * @endcode
+     *
+     * \sa_h5cpp
+     * \sa_hdf5
+     * @sa h5::create h5::open @ref link_handle_reference
+     *     "Handles, Descriptors, and Property Lists"
+     */
+    template<class hid_t>
+    inline H5CPP_ATTR_DELETE_RET(hid_t)
+    adelete(const hid_t& parent, const std::string& name) {
         H5CPP_CHECK_NZ(
-            H5Adelete(static_cast<hid_t>(parent), name.c_str()),
+            H5Adelete(static_cast<::hid_t>(parent), name.c_str()),
             h5::error::io::attribute::delete_,
             "couldn't delete attribute");
     }

h5cpp/H5Aopen.hpp

@@ -6,15 +6,59 @@
 #include "H5Acreate.hpp"
 #include <string>
 #include <type_traits>
+
+// Return-type macro for h5::open(parent, path, acpl) attribute overload.
+// Real compile: SFINAE-constrained h5::impl::attr_parent_t<hid_t> alias.
+// Doxygen     : plain h5::at_t. See H5Acreate.hpp for the rationale.
+#ifdef H5CPP_DOXYGEN
+#  define H5CPP_ATTR_OPEN_RET(hid_t) h5::at_t
+#else
+#  define H5CPP_ATTR_OPEN_RET(hid_t) h5::impl::attr_parent_t<hid_t>
+#endif
+
 namespace h5 {
-	template<class HID_T>
-	inline std::enable_if_t<h5::impl::is_valid_attr<HID_T>::value,
-    h5::at_t> open(const  HID_T& parent, const std::string& path, const h5::acpl_t& acpl = h5::default_acpl ){
+	/**
+	 * \func_attr_hdr
+	 * @brief Open an existing attribute by name on a parent HDF5 object.
+	 *
+	 * Lookup is by attribute name relative to `parent`. The returned
+	 * `h5::at_t` is RAII-managed; the underlying CAPI handle is closed
+	 * via `H5Aclose` on scope exit. Use @ref h5::aread to retrieve the
+	 * value, or pass the handle to `h5::awrite` overloads that take an
+	 * already-open attribute.
+	 *
+	 * @param parent  open parent handle: raw `::hid_t`, `h5::gr_t`, `h5::ds_t`, `h5::ob_t`, or `h5::dt_t<T>` — enforced at compile
+	 *                time via `h5::impl::is_valid_attr`. Typed `h5::fd_t` is **not** accepted directly; pass `static_cast<::hid_t>(fd)`.
+	 * @param path    attribute name (UTF-8); resolved relative to `parent`.
+	 * @param acpl    attribute creation property list (`h5::acpl_t`); defaults to `h5::default_acpl`.
+	 *
+	 * @tparam hid_t  deduced from the `parent` argument; must satisfy `h5::impl::is_valid_attr<hid_t>::value`.
+	 * @return `h5::at_t` RAII handle owning the opened attribute id; closes automatically via `H5Aclose` on scope exit. Throws on failure.
+	 *
+	 * @throws h5::error::io::attribute::open  on `H5Aopen` failure (attribute
+	 *         not present, parent does not exist, invalid acpl).
+	 *
+	 * <br/><b>example:</b>
+	 * @code
+	 * h5::fd_t fd = h5::open("file.h5", H5F_ACC_RDONLY);
+	 * h5::ds_t ds = h5::open(fd, "/grid/data");
+	 * h5::at_t att = h5::open(ds, "spacing");
+	 * auto axes = h5::aread<std::vector<float>>(ds, "spacing");
+	 * @endcode
+	 *
+	 * \sa_h5cpp
+	 * \sa_hdf5
+	 * @sa h5::aread h5::awrite @ref link_handle_reference
+	 *     "Handles, Descriptors, and Property Lists"
+	 */
+	template<class hid_t>
+	inline H5CPP_ATTR_OPEN_RET(hid_t)
+	open(const hid_t& parent, const std::string& path, const h5::acpl_t& acpl = h5::default_acpl ){
 
 		H5CPP_CHECK_PROP( acpl, h5::error::io::attribute::open, "invalid attribute creation property" );
-		hid_t attr = H5I_UNINIT;
-	   	H5CPP_CHECK_NZ(( attr = H5Aopen( static_cast<hid_t>(parent),
-			path.c_str(), static_cast<hid_t>(acpl))), h5::error::io::attribute::open, "can't open attribute..." );
+		::hid_t attr = H5I_UNINIT;
+	   	H5CPP_CHECK_NZ(( attr = H5Aopen( static_cast<::hid_t>(parent),
+			path.c_str(), static_cast<::hid_t>(acpl))), h5::error::io::attribute::open, "can't open attribute..." );
      	return  h5::at_t{attr};
     }
 }