added more documentation for GLObject::generate

src/GLObject.cpp

@@ -17,9 +17,22 @@ using namespace sb;
  * or a custom function that does something in addition to calling the appropriate GL deleter function). */
 GLObject::GLObject(deleter_function deleter) : deleter(deleter) {}
 
-/* This generator passed in from the derived class will be called to generate a new ID. It is limited to a
- * single ID. For generating and managing multiple IDs with a single class, this method and others will have
- * to be overwritten. */
+/*!
+ * The supplied `sb::GLObject::generator_function` will be called to generate a new ID. This can be used, for example,
+ * by a member function override in a derived class to specify which OpenGL generate function to use, like `glGenTextures`
+ * or `glGenBuffers`.
+ *
+ * Although OpenGL generation functions support generating multiple object IDs, generation through this function is limited
+ * to a single ID. For generating and managing multiple IDs with a single class, this method and others will have to be
+ * overwritten.
+ *
+ * Because the ID is being reassigned to a new `std::shared_ptr`, the `sb::GLObject::deleter_function` passed to the
+ * constructor will be automatically called, meaning the currently allocated GL object memory will be freed if this object
+ * had previously generated an ID. To keep the object in memory, create a new `sb::GLObject` instead of calling
+ * `sb::GLObject::generate` again.
+ *
+ * @param generator  A function that will be called to generate an OpenGL ID for this object
+ */
 void GLObject::generate(generator_function generator)
 {
     GLuint id;