From 30ae62f62aa4255b3c9f9b7343bc459a02958a23 Mon Sep 17 00:00:00 2001 From: parker Date: Wed, 20 Aug 2025 13:18:55 +0100 Subject: [PATCH] docs: add doxygen comments for Attribute, AttributeHandle, and AttributeHandleRO --- src/Engine/Operator/Attribute.h | 2 +- src/Engine/Operator/AttributeHandle.h | 93 ++++++++++++++++++++++++--- 2 files changed, 85 insertions(+), 10 deletions(-) diff --git a/src/Engine/Operator/Attribute.h b/src/Engine/Operator/Attribute.h index 304a04e..7af3de0 100644 --- a/src/Engine/Operator/Attribute.h +++ b/src/Engine/Operator/Attribute.h @@ -41,7 +41,7 @@ namespace enzo{ * @brief Construct a new attribute and initialize its typed storage. * * @param name Human-readable identifier, spaces are not permitted (unique within a collection/scope). - * @param type #ga::AttributeType that attribute values will be stored in. + * @param type Attribute data type that values will be stored in. * */ Attribute(std::string name, ga::AttributeType type); diff --git a/src/Engine/Operator/AttributeHandle.h b/src/Engine/Operator/AttributeHandle.h index 6f67901..d58dc8d 100644 --- a/src/Engine/Operator/AttributeHandle.h +++ b/src/Engine/Operator/AttributeHandle.h @@ -13,12 +13,43 @@ namespace enzo::ga{ +/** +* @class enzo::ga::AttributeHandle +* @brief Read write accessor for #enzo::ga::Attribute +* +* @tparam T C++ value type matching the Attribute’s logical type +* (e.g., bt::intT, bt::floatT, bt::Vector3, bt::boolT). +* +* An Attribute Handle is a typed view into an attribute’s storage. +* It binds at construction to a concrete type and exposes operations +* like reserving capacity, appending values, and reading/writing by +* index. Because the handle uses templating, most misuse is caught +* at compile time, and runtime guards raise errors if an attribute/handle +* type combination isn’t accounted for. In the future implicit casting +* can be added for convenience. Handles don’t own data, +* they just reference the attribute’s storage. +* +* There is also a read-only handle variant that provides the same +* typed accessors without mutation. This is useful when an operator +* needs to inspect data but must not modify it, when the engine exposes +* attributes to user code with limited permissions, or when implementing +* const member functions that require attribute access. +* +* Together, attributes define the schema and storage, while handles +* provide the typed access that nodes and tools use to operate on data directly. +*/ template class AttributeHandle { public: ga::AttributeType type_; + /** + * @brief Construct a new typed handle linked to a target attribute + * + * @param attribute The target attribute this handle will modify + * + */ AttributeHandle(std::shared_ptr attribute) { type_ = attribute->getType(); @@ -53,6 +84,12 @@ public: } } + /** + * @brief Adds an element to the end of the attribute. + * + * @param The element value the value to add to the attribute. + * + */ void addValue(T value) { // TODO:make this private (primitive friend classes only) @@ -60,35 +97,65 @@ public: } + /** + * @brief Reserves more space in the attribute to add new elements + * + * This is important when adding many elements to the attribute as automatic resizing is expensive. + * + * @param newCap The new maximum number of elements the attribute can hold before needing to automatically allocate more. + * + */ void reserve(std::size_t newCap) { data_->reserve(newCap); } // TODO: replace with iterator + /** + * @brief Gets a vector containing all the values stored in this attribute. + * + * @todo Replace with an iterator for accessing many values. + * + * @returns A vector containing all the values stored in this attribute. + * + */ std::vector getAllValues() const { return {data_->begin(), data_->end()}; } + /** + * @brief Gets the number of element stored in the attribute + */ size_t getSize() const { return data_->size(); } - T getValue(size_t pos) const + /** + * @brief Gets the value at a given offset + * @returns The value stored at a given offset + * @todo protect against invalid positions + * @todo Add implicit casting between types (eg. if T is int but the parameter's #ga::AttributeType is floatT 5.3 return 5) + */ + T getValue(size_t offset) const { - // TODO:protect against invalid positions - // TODO: cast types - return (*data_)[pos]; + return (*data_)[offset]; } - void setValue(size_t pos, const T& value) + /** + * @brief Sets the value at a given offset. + * @todo protect against invalid positions + * @todo Add implicit casting between types (eg. if T is int but the parameter's #ga::AttributeType is floatT 5.3 return 5) + */ + void setValue(size_t offset, const T& value) { - // TODO:protect against invalid positions - // TODO: cast types - (*data_)[pos] = value; + (*data_)[offset] = value; } + + /** + * @brief Returs the attribute name as a string + */ std::string getName() const { return name_; @@ -120,11 +187,16 @@ using AttributeHandleVector3 = AttributeHandle; using AttributeHandleBool = AttributeHandle; template +/** +* @brief Read only accessor for #enzo::ga::Attribute +* @copydetails AttributeHandle +*/ class AttributeHandleRO { public: ga::AttributeType type_; + /// @copydoc AttributeHandle::AttributeHandle AttributeHandleRO(std::shared_ptr attribute) { type_ = attribute->getType(); @@ -160,17 +232,19 @@ public: } - // TODO: replace with iterator + /// @copydoc AttributeHandle::getAllValues std::vector getAllValues() const { return {data_->begin(), data_->end()}; } + /// @copydoc AttributeHandle::getSize size_t getSize() const { return data_->size(); } + /// @copydoc AttributeHandle::getValue T getValue(size_t pos) const { // TODO:protect against invalid positions @@ -178,6 +252,7 @@ public: return (*data_)[pos]; } + /// @copydoc AttributeHandle::getName std::string getName() const { return name_;