docs: add doxygen comments for Geometry class

src/Engine/Operator/Geometry.h

@@ -24,56 +24,214 @@ using F_index  = HeMesh::Face_index;
 
 using attributeIterator = std::vector<std::shared_ptr<ga::Attribute>>::iterator;
 
+/**
+* @class enzo::geo::Geometry
+* @brief [Attribute](@ref enzo::ga::Attribute) based geometry container exchanged and modified by nodes.
+*
+* The Geometry class represents the core data being passed between nodes
+* in the engine. It is the operand of the network. Nodes read, modify,
+* and output geometry, which is then used to populate the viewport and
+* the geometry spreadsheet. Geometry is stored in an [attribute](@ref enzo::ga::Attribute) based
+* structure, similar to a spreadsheet, where each column is an [attribute](@ref enzo::ga::Attribute)
+* owned by points, vertices, primitives, or the global context. Most geometry
+* information, including built in properties such as positions and connectivity,
+* is stored through this same system. These built in [attributes](@ref enzo::ga::Attribute) are intrinsic,
+* but they share the same base as user-defined [attributes](@ref enzo::ga::Attribute) to keep the data
+* model consistent.
+*
+* The class provides methods for constructing and querying geometry, including
+* adding points and faces, computing normals, and building a CGAL half-edge
+* mesh representation. It also exposes accessors for reading positions,
+* primitive connectivity, and vertex data, while tracking special cases
+* such as isolated points.
+*
+* @post Geometry in instatiated with some intrinsic attributes required
+* to construct geometry, such as P (position) on point attributes, vertexCount
+* and closed on primitive attributes, and point on vertices. It is recommended
+* not to modify these directy but instead use the helper functions.
+*/
 class Geometry
 {
 public:
-    Geometry();
+   /**
-    Geometry(const Geometry& other);
+    * @brief Assignment operator. Performs a deep copy of another Geometry.
+    * @param rhs The Geometry object to copy from.
+    * @return Reference to this Geometry.
+    */
     Geometry& operator=(const Geometry& rhs);
+
+    /**
+    * @brief Adds an integer attribute to the geometry.
+    * @param owner The attribute owner (point, vertex, primitive, detail).
+    * @param name The name of the attribute.
+    * @return Handle to the created integer attribute.
+    */
     ga::AttributeHandle<bt::intT> addIntAttribute(ga::AttributeOwner owner, std::string name);
+
+    /**
+    * @brief Adds a boolean attribute to the geometry.
+    * @param owner The attribute owner (point, vertex, primitive, detail).
+    * @param name The name of the attribute.
+    * @return Handle to the created boolean attribute.
+    */
     ga::AttributeHandleBool addBoolAttribute(ga::AttributeOwner owner, std::string name);
+
+    /**
+    * @brief Adds a 3D vector attribute to the geometry.
+    * @param owner The attribute owner (point, vertex, primitive, detail).
+    * @param name The name of the attribute.
+    * @return Handle to the created Vector3 attribute.
+    */
     ga::AttributeHandle<bt::Vector3> addVector3Attribute(ga::AttributeOwner owner, std::string name);
-    // TODO: return weak ptr
+
+    /**
+    * @brief Retrieves an attribute by its name.
+    * @param owner The attribute owner.
+    * @param name The name of the attribute.
+    * @return Shared pointer to the attribute if found, otherwise nullptr.
+    */
     std::shared_ptr<ga::Attribute> getAttribByName(ga::AttributeOwner owner, std::string name);
 
+    /**
+    * @brief Gets the number of attributes owned by a specific element type.
+    * @param owner The attribute owner.
+    * @return Number of attributes.
+    */
     const size_t getNumAttributes(const ga::AttributeOwner owner) const;
-    std::weak_ptr<const ga::Attribute> getAttributeByIndex(ga::AttributeOwner owner, unsigned int index) const;
-    // attributeIterator attributesBegin(const ga::AttributeOwner owner);
-    // attributeIterator attributesEnd(const ga::AttributeOwner owner);
 
-    std::vector<bt::Vector3> derivePointNormals();
+    /**
+    * @brief Retrieves an attribute by its index.
+    * @param owner The attribute owner.
+    * @param index Index of the attribute.
+    * @return Weak pointer to the attribute.
+    */
+    std::weak_ptr<const ga::Attribute> getAttributeByIndex(ga::AttributeOwner owner, unsigned int index) const;
+
+    /**
+    * @brief Computes per-point normals for the geometry.
+    * @return Vector of computed normals corresponding to each point.
+    */
+    // std::vector<bt::Vector3> derivePointNormals();
+
+    /**
+    * @brief Builds a CGAL half-edge mesh representation of the geometry.
+    * @return The constructed half-edge mesh.
+    */
     HeMesh computeHalfEdgeMesh();
 
-    // build geometry
+    /**
+    * @brief Adds a polygonal face to the geometry.
+    * @param pointOffsets Offsets of the points forming the face.
+    * @param closed Whether the face is closed (default true).
+    */
     void addFace(const std::vector<ga::Offset>& pointOffsets, bool closed=true);
-    template <typename... Args>
-    void addFace(Args... args)
-    {
-        std::vector<ga::Offset> pointOffsets = { static_cast<ga::Offset>(args)... };
-        addFace(pointOffsets);
 
-    }
+    /**
+    * @brief Adds a point to the geometry.
+    * @param pos Position of the new point.
+    */
     void addPoint(const bt::Vector3& pos);
 
+    /**
+    * @brief Iterator to the beginning of the set of solo (isolated) points.
+    * @return Const iterator to the first solo point.
+    */
     std::set<ga::Offset>::const_iterator soloPointsBegin();
+
+    /**
+    * @brief Iterator to the end of the set of solo (isolated) points.
+    * @return Const iterator past the last solo point.
+    */
     std::set<ga::Offset>::const_iterator soloPointsEnd();
 
+    /**
+    * @brief Sets the position of a point.
+    * @param offset Offset of the point.
+    * @param pos New position.
+    */
     void setPointPos(const ga::Offset offset, const bt::Vector3& pos);
 
-    ga::Offset      getPrimStartVertex(ga::Offset primOffset) const; // returns the first vertex of the primitive
+    /**
-    bt::Vector3     getPosFromVert(ga::Offset vertexOffset) const;
+    * @brief Gets the first vertex of a primitive.
-    bt::Vector3     getPointPos(ga::Offset pointOffset) const;
+    * @param primOffset Offset of the primitive.
-    unsigned int    getPrimVertCount(ga::Offset primOffset) const;
+    * @return Offset of the first vertex.
-    ga::Offset      getVertexPrim(ga::Offset vertexOffset) const;
+    */
-    ga::Offset      getNumPrims() const;
+    ga::Offset getPrimStartVertex(ga::Offset primOffset) const;
-    ga::Offset      getNumVerts() const;
-    ga::Offset      getNumPoints() const;
-    ga::Offset      getNumSoloPoints() const;
 
+    /**
+    * @brief Gets the 3 dimensional position from a vertex offset.
+    * @param vertexOffset Offset of the vertex.
+    * @return Position of the vertex.
+    */
+    bt::Vector3 getPosFromVert(ga::Offset vertexOffset) const;
+
+    /**
+    * @brief Gets the position of a point.
+    * @param pointOffset Offset of the point.
+    * @return Position of the point.
+    */
+    bt::Vector3 getPointPos(ga::Offset pointOffset) const;
+
+    /**
+    * @brief Gets the number of vertices in a primitive.
+    * @param primOffset Offset of the primitive.
+    * @return Number of vertices.
+    */
+    unsigned int getPrimVertCount(ga::Offset primOffset) const;
+
+    /**
+    * @brief Gets the primitive that owns a given vertex.
+    * @param vertexOffset Offset of the vertex.
+    * @return Offset of the owning primitive.
+    */
+    ga::Offset getVertexPrim(ga::Offset vertexOffset) const;
+
+    /**
+    * @brief Gets the number of primitives in the geometry.
+    * @return Number of primitives.
+    */
+    ga::Offset getNumPrims() const;
+
+    /**
+    * @brief Gets the number of vertices in the geometry.
+    * @return Number of vertices.
+    */
+    ga::Offset getNumVerts() const;
+
+    /**
+    * @brief Gets the number of points in the geometry.
+    * @return Number of points.
+    */
+    ga::Offset getNumPoints() const;
+
+    /**
+    * @brief Gets the number of isolated points in the geometry.
+    * Isolated points are points that are not connnected to any other point
+    * and don't belong to a primitive.
+    * @return Number of solo points.
+    */
+    ga::Offset getNumSoloPoints() const;
+
+    /**
+    * @brief Checks if a primitive is closed or open.
+    *
+    * Open primitives are treated and rendered as curves.
+    *
+    * @param primOffset Offset of the primitive.
+    * @return True if the primitive is closed, false otherwise.
+    */
     bt::boolT isClosed(ga::Offset primOffset) const;
 
+    /**
+    * @brief Merges another geometry into this one.
+    * @param other The geometry to merge.
+    */
     void merge(Geometry& other);
 
+    /**
+    * @brief Computes the starting vertex for each primitive in the geometry.
+    * @todo Automatically lazy evaluate when requested (make thread safe)
+    */
     void computePrimStartVertices() const;
 private:
     using attribVector = std::vector<std::shared_ptr<ga::Attribute>>;

src/Engine/Types.h

@@ -11,6 +11,14 @@ namespace enzo
 
     namespace ga
     {
+        /**
+         * @brief The segment of geometry that owns a particular attribute
+         *
+         * - POINT attributes are stored per point, these attributes have an value for each point.
+         * - VERTEX attributes are stored per vertex, these attributes have an value for each vertex.
+         * - PRIMITIVE attributes are stored per primitive, these attributes have an value for each primitive.
+         * - GLOBAL attributes are stored globaly, these attributes only have one value.
+         */
         enum class AttributeOwner
         {
             POINT,
@@ -31,6 +39,14 @@ namespace enzo
         };
         using AttrType = AttributeType;
         using AttrOwner = AttributeOwner;
+        /**
+         * @brief ga::Offset is the index of an element in a given AttributeOwner.
+         *
+         * Eg. point index, vertex index, primitive index, or global index.
+         * This different but similar in concept to a point number. This
+         * value will stay consistant through geometry modification such
+         * as adding and deleting points unlress defragmented.
+         */
         using Offset = size_t;
     }
     // basic types types