docs: added comments

src/lepus/engine/Objects/Mesh.h

@@ -19,17 +19,24 @@ namespace lepus
 
         namespace objects
         {
+            /// @brief Base class for Mesh data in the engine.
+            ///
+            /// Can be specialised for different parts of the engine (e.g.rendering, physics) by inheriting and adding API-specific logic as needed.
             class Mesh
             {
                 private:
+                /// @brief The vertex format used by the mesh data.
                 MeshVertexFormat m_Format = MeshVertexFormat::Invalid;
 
+                /// @brief Vertex data
                 void* m_Vertices = nullptr;
                 size_t m_szVertices = 0;
 
+                /// @brief Index data (optional, but common enough to be included in the base class for simplicity's sake)
                 uint32_t* m_Indices = nullptr;
                 size_t m_IndexCount = 0;
 
+                /// @brief Does this Mesh own the vertex/index data? If true, this Mesh will delete the data when Dispose is called.
                 bool m_OwnData = false;
                 bool m_IsIndexed = false;
 
@@ -48,6 +55,7 @@ namespace lepus
                     m_OwnData = false;
                 }
 
+                /// @brief Always called after constructing a new Mesh instance (excluding move/copy ctors).
                 inline virtual void InitInternal()
                 {
 
@@ -94,12 +102,14 @@ namespace lepus
                 }
 
                 /// @brief Move assignment
-                /// @param other Rvalue to assign
+                /// @param other Mesh rvalue to assign
                 /// @return The current object with vertices, indices and any metadata from the rvalue. 
                 Mesh& operator=(Mesh&& other)
                 {
+                    // Prevent self-assignment.
                     if (this != &other)
                     {
+                        // Make sure our data is disposed first if necessary so memory doesn't leak.
                         Dispose();
 
                         m_Format = other.m_Format;
@@ -125,19 +135,36 @@ namespace lepus
                     return *this;
                 }
 
+                /// @brief Default constructor. Initialises an empty mesh with just a vertex format and no vertices.
+                /// @param format Vertex format to use.
                 inline void Init(MeshVertexFormat format = MeshVertexFormat::VVV)
                 {
                     m_Format = format;
-                    m_OwnData = true;
+                    m_OwnData = false;
+                    m_IsIndexed = false;
+                    m_szVertices = 0;
+                    m_IndexCount = 0;
+                    m_Vertices = nullptr;
+                    m_Indices = nullptr;
 
                     InitInternal();
                 }
 
+                /// @brief Initialises the Mesh with geometry data from a built-in primitive.
+                /// @param primitive A built-in primitive instance from LepusUtility.
+                /// @param copy Should the data be copied?
                 inline void Init(const lepus::utility::Primitive& primitive, bool copy = false)
                 {
                     Init((void*)primitive.GetVertices(), primitive.VertexBufferSize(), MeshVertexFormat::VVV, (uint32_t*)primitive.GetIndices(), primitive.IndexCount(), copy);
                 }
 
+                /// @brief Initialises the Mesh with provided geometry data.
+                /// @param vertices Vertex data
+                /// @param szVertices Size of the vertex data (in bytes)
+                /// @param format Vertex data format
+                /// @param indices Index data. Optional - pass nullptr for non-indexed.
+                /// @param indexCount Number of indices.
+                /// @param copy Should the data be copied?
                 inline void Init(void* vertices, size_t szVertices, MeshVertexFormat format = MeshVertexFormat::VVV, uint32_t* indices = nullptr, size_t indexCount = 0, bool copy = false)
                 {
                     m_Format = format;
@@ -174,18 +201,26 @@ namespace lepus
                     InitInternal();
                 }
 
+                /// @brief Gets the vertex format used by this Mesh.
+                /// @return The MeshVertexFormat this Mesh was initialised with.
                 inline MeshVertexFormat GetFormat() const { return m_Format; }
 
+                /// @brief Gets the pointer to vertex data used by this Mesh.
+                /// @return A constant pointer to the vertex data.
                 const void* GetVertices() const
                 {
                     return m_Vertices;
                 }
 
+                /// @brief Gets the pointer to index data used by this Mesh.
+                /// @return A constant pointer to the index data.
                 const uint32_t* GetIndices() const
                 {
                     return m_Indices;
                 }
 
+                /// @brief Gets the size of a single vertex based on the vertex format used by this Mesh.
+                /// @return An unsigned 8-bit integer defining a single vertex size.
                 uint8_t GetSingleVertexSize() const
                 {
                     switch (m_Format)
@@ -198,26 +233,35 @@ namespace lepus
                     }
                 }
 
+                /// @brief Gets the number of vertices in this Mesh.
+                /// @return An unsigned 64-bit integer defining the number of vertices (TODO: that's a maximum of 18,446,744,073,709,551,615 vertices... do we really need 64-bit for that?)
                 size_t inline VertexCount() const
                 {
                     return m_szVertices / GetSingleVertexSize();
                 }
 
+                /// @brief Gets the size of the vertex data.
+                /// @return An unsigned 64-bit integer defining the size of the vertex data (in bytes).
                 size_t inline VertexBufferSize() const
                 {
                     return m_szVertices;
                 }
 
+                /// @brief Gets the size of the index data.
+                /// @return An unsigned 64-bit integer defining the size of the index data (in bytes).
                 size_t inline IndexBufferSize() const
                 {
                     return m_IndexCount * sizeof(uint32_t);
                 }
 
+                /// @brief Gets the number of indices in this Mesh.
+                /// @return An unsigned 64-bit integer defining the number of indices that make up this Mesh (TODO: again, isn't 64 bits overkill?)
                 size_t inline IndexCount() const
                 {
                     return m_IndexCount;
                 }
 
+                /// @brief Releases any resources and data held by this Mesh as needed.
                 inline virtual void Dispose()
                 {
                     if (m_OwnData)
@@ -239,9 +283,7 @@ namespace lepus
                 }
             };
         }
-    } // namespace engine
-
-} // namespace lepus
-
+    }
+}
 
 #endif

src/lepus/gfx/GraphicsEngine/Apis/ApiGL/ApiGL.cpp

@@ -18,10 +18,13 @@ void GraphicsApiGL::SetupBuffers()
 {
 	glBindVertexArray(m_Pipeline.vao);
 
+	// Creating a mesh from built-in primitive geometry.
 	m_Meshes[0] = GLMesh(lepus::utility::Primitives::Cube());
 	m_Pipeline.vbo[0] = m_Meshes[0].GetVBO();
 	m_Pipeline.ibo[0] = m_Meshes[0].GetIBO();
 
+	// Creating a mesh by copying the first mesh.
+	// Vertex & index data is shared with the first mesh, but uploaded to a separate pair of OpenGL buffers.
 	m_Meshes[1] = GLMesh(m_Meshes[0]);
 	m_Pipeline.vbo[1] = m_Meshes[1].GetVBO();
 	m_Pipeline.ibo[1] = m_Meshes[1].GetIBO();

src/lepus/gfx/GraphicsEngine/Apis/ApiGL/Types/GLMesh.h

@@ -8,6 +8,7 @@ namespace lepus
 {
     namespace gfx
     {
+        /// @brief A Mesh specialisation to create and manage OpenGL resources for mesh data as needed.
         class GLMesh : protected lepus::engine::objects::Mesh
         {
             private:
@@ -17,7 +18,9 @@ namespace lepus
             bool m_HasVBO;
             bool m_HasIBO;
 
+            /// @brief Creates a Vertex Buffer Object for the mesh data.
             void _CreateVBO();
+            /// @brief Creates an Index Buffer Object for the mesh data.
             void _CreateIBO();
 
             protected:
@@ -29,7 +32,7 @@ namespace lepus
                 m_HasVBO = false;
 
                 // Avoid creating a VBO or IBO if the size is 0 - this is likely because the mesh is being created on the stack
-                // before a VAO was bound. This will only result in a crash.
+                // with the default constructor before a VAO was bound. This will only result in a crash.
                 if (VertexBufferSize() > 0)
                 {
                     _CreateVBO();
@@ -50,22 +53,33 @@ namespace lepus
             public:
             LEPUS_MESH_CONSTRUCTOR(GLMesh);
 
+            /// @brief Copy constructor
+            /// @param other GLMesh object to copy.
             GLMesh(const GLMesh& other)
             {
                 CopyInternal(other);
             }
 
+            /// @brief Move constructor. Moves all base Mesh data (including vertices and indices) as well as OpenGL buffer names.
+            /// @param other GLMesh rvalue to move data from.
             GLMesh(GLMesh&& other)
             {
+                // Calls the move-assignment operator as the logic is the same.
                 *this = std::move(other);
             }
 
+            /// @brief Copy-assignment operator
+            /// @param other GLMesh object to copy.
+            /// @return A reference to a GLMesh object with data internally copied from the assigned object.
             GLMesh& operator=(const GLMesh& other)
             {
                 CopyInternal(other);
                 return *this;
             }
 
+            /// @brief Move-assignment operator
+            /// @param other GLMesh rvalue to move data from.
+            /// @return A reference to a GLMesh object with vertex & index data as well as OpenGL buffers moved from the assigned object.
             GLMesh& operator=(GLMesh&& other)
             {
                 *((Mesh*)this) = (Mesh)other;
@@ -78,9 +92,15 @@ namespace lepus
                 return *this;
             }
 
+            /// @brief Gets the Vertex Buffer Object used for this Mesh.
+            /// @return An OpenGL Vertex Buffer Object name that can be used with glBindBuffer.
             inline GLuint GetVBO() const { return m_VBO; }
+
+            /// @brief Gets the Index Buffer Object used for this Mesh.
+            /// @return An OpenGL Index Buffer Object name that can be used with glBindBuffer.
             inline GLuint GetIBO() const { return m_IBO; }
 
+            /// @brief Specialised Dispose() that, in addition to calling base Dispose(), releases OpenGL Vertex and Index Buffer Objects as needed.
             inline void Dispose() override
             {
                 Mesh::Dispose();

src/lepus/utility/Primitives.h

@@ -132,6 +132,9 @@ namespace lepus
             private:
             static Primitives _shared;
             public:
+
+            /// @brief Gets the global Primitives instance.
+            /// @return A reference to the global Primitives object containing shared instances of Primitive objects.
             static Primitives& Shared() { return _shared; };
 
 #define LEPUS_UTILITY_PRIMITIVE_SHARED(PrimitiveName) \