Added some comments

source/shader/include/ShaderProgramBuilder.hpp

@@ -6,6 +6,13 @@
 
 namespace ugly{
 
+/**
+ * \brief Builder class for OpenGL shader and programs.
+ * 
+ * On initialization, creates a new OpenGL program. Attach and compile shader
+ * sources using `attachFrom*`. Link and get the program with `link()`. User is
+ * responsible of managing returned program's lifetime, including destroying it.
+ */
 class ShaderProgramBuilder {
 private:
     GLuint mProgram;
@@ -13,10 +20,36 @@ private:
 public:
     ShaderProgramBuilder();
     ~ShaderProgramBuilder();
+    /**
+     * \brief Deletes program and starts from scratch.
+     */
     void reset();
+    /**
+     * \brief Creates, compiles, and attaches a shader.
+     * \param type Specifies the type of shader to be created. Must be one of
+     *             \c GL_VERTEX_SHADER, \c GL_GEOMETRY_SHADER or
+     *             \c GL_FRAGMENT_SHADER .
+     * \param string Shader source code.
+     * \param length Bytes to read from \p string, \c 0 reads until NUL byte.
+     * \returns *this
+     */
     ShaderProgramBuilder &attachFromMemory(GLenum type, const GLchar *string, GLint length = 0);
+    /**
+     * \brief Creates, compiles, and attaches a shader. Reads source from file.
+     * \param type Specifies the type of shader to be created. Must be one of
+     *             \c GL_VERTEX_SHADER, \c GL_GEOMETRY_SHADER or
+     *             \c GL_FRAGMENT_SHADER .
+     * \param filename Shader source code file.
+     * \returns \c *this
+     */
     ShaderProgramBuilder &attachFromFile(GLenum type, const char *filename);
-    GLuint link();
+    /**
+     * \brief Links OpenGL program after attaching sources.
+     * 
+     * After this function is called the builder object is reset.
+     * \return OpenGL object name. User is reponsible for managing it.
+     */
+    [[nodiscard]] GLuint link();
 };
 
 }

source/shader/src/ShaderProgramBuilder.cpp

@@ -13,6 +13,7 @@ ShaderProgramBuilder::ShaderProgramBuilder():
 
 
 ShaderProgramBuilder::~ShaderProgramBuilder() {
+    // link() sets mProgram=0 to prevent it from being deleted after being given to the user.
     if(mProgram != 0) {
         glDeleteProgram(mProgram);
     }
@@ -21,8 +22,8 @@ ShaderProgramBuilder::~ShaderProgramBuilder() {
 
 void ShaderProgramBuilder::reset() {
     using namespace std;
-    ShaderProgramBuilder b;
-    swap(*this, b);
+    ShaderProgramBuilder newBuilder;
+    swap(*this, newBuilder);
 }
 
 
@@ -31,6 +32,7 @@ ShaderProgramBuilder &ShaderProgramBuilder::attachFromMemory(GLenum type, const
     glShaderSource(shader, 1, &string, length != 0 ? &length : NULL);
     glCompileShader(shader);
 
+    // Check for shader compilation errors
     GLint status;
     glGetShaderiv(shader, GL_COMPILE_STATUS, &status);
     if(status != GL_TRUE) {
@@ -40,6 +42,7 @@ ShaderProgramBuilder &ShaderProgramBuilder::attachFromMemory(GLenum type, const
         log("failed to compile shader:\n\t{}", buf);
     }
 
+    // After the shader is attached, it can safely be marked for deletion and OpenGL will handle it.
     glAttachShader(mProgram, shader);
     glDeleteShader(shader);
     return *this;
@@ -47,6 +50,7 @@ ShaderProgramBuilder &ShaderProgramBuilder::attachFromMemory(GLenum type, const
 
 
 ShaderProgramBuilder &ShaderProgramBuilder::attachFromFile(GLenum type, const char *filename) {
+    // Load entire file to memory then let attachFromMemory handle it.
     auto file = std::filebuf{};
     auto ss = std::ostringstream{};
 
@@ -64,6 +68,7 @@ ShaderProgramBuilder &ShaderProgramBuilder::attachFromFile(GLenum type, const ch
 GLuint ShaderProgramBuilder::link() {
     glLinkProgram(mProgram);
     
+    // Check for program linking errors
     GLint status;
     glGetProgramiv(mProgram, GL_LINK_STATUS, &status);
     if(status != GL_TRUE) {
@@ -72,6 +77,7 @@ GLuint ShaderProgramBuilder::link() {
         log("failed to link program:\n\t{}", buf);
     }
 
+    // reset() this object but take care of not deleting the program returned to the caller.
     auto result = mProgram;
     mProgram = 0;
     reset();