Cleanup: GPU: Update classes comments

This should avoid confusion about what is a class and what is an opaque
pointer.

source/blender/gpu/GPU_uniform_buffer.h

@@ -19,6 +19,13 @@
 
 /** \file
  * \ingroup gpu
+ *
+ * Uniform buffers API. Used to handle many uniforms update at once.
+ * Make sure that the data structure is compatible with what the implementation expect.
+ * (see "7.6.2.2 Standard Uniform Block Layout" from the OpenGL spec for more info about std140
+ * layout)
+ * Rule of thumb: Padding to 16bytes, don't use vec3, don't use arrays of anything that is not vec4
+ * aligned .
  */
 
 #pragma once
@@ -29,7 +36,7 @@ extern "C" {
 
 struct ListBase;
 
-/** Opaque pointer */
+/** Opaque pointer hiding blender::gpu::UniformBuf. */
 typedef struct GPUUniformBuf {
   void *dummy;
 } GPUUniformBuf;

source/blender/gpu/intern/gpu_batch_private.hh

@@ -32,6 +32,10 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * Base class which is then specialized for each implementation (GL, VK, ...).
+ * NOTE: Extends GPUBatch as we still needs to expose some of the internals to the outside C code.
+ **/
 class Batch : public GPUBatch {
  public:
   Batch(){};

source/blender/gpu/intern/gpu_drawlist_private.hh

@@ -28,6 +28,10 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * Implementation of Multi Draw Indirect.
+ * Base class which is then specialized for each implementation (GL, VK, ...).
+ **/
 class DrawList {
  public:
   virtual ~DrawList(){};

source/blender/gpu/intern/gpu_shader_interface.hh

@@ -45,6 +45,10 @@ typedef struct ShaderInput {
   int32_t binding;
 } ShaderInput;
 
+/**
+ * Implementation of Shader interface.
+ * Base class which is then specialized for each implementation (GL, VK, ...).
+ **/
 class ShaderInterface {
   /* TODO(fclem) should be protected. */
  public:

source/blender/gpu/intern/gpu_shader_private.hh

@@ -29,6 +29,10 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * Implementation of shader compilation and uniforms handling.
+ * Base class which is then specialized for each implementation (GL, VK, ...).
+ **/
 class Shader {
  public:
   /** Uniform & attribute locations for shader. */

source/blender/gpu/intern/gpu_state_private.hh

@@ -151,6 +151,10 @@ inline GPUStateMutable operator~(const GPUStateMutable &a)
   return r;
 }
 
+/**
+ * State manager keeping track of the draw state and applying it before drawing.
+ * Base class which is then specialized for each implementation (GL, VK, ...).
+ **/
 class GPUStateManager {
  public:
   GPUState state;

source/blender/gpu/intern/gpu_uniform_buffer_private.hh

@@ -33,6 +33,10 @@ namespace gpu {
 #  define DEBUG_NAME_LEN 64
 #endif
 
+/**
+ * Implementation of Uniform Buffers.
+ * Base class which is then specialized for each implementation (GL, VK, ...).
+ **/
 class UniformBuf {
  protected:
   /** Data size in bytes. */

source/blender/gpu/opengl/gl_drawlist.hh

@@ -19,6 +19,9 @@
 
 /** \file
  * \ingroup gpu
+ *
+ * Implementation of Multi Draw Indirect using OpenGL.
+ * Fallback if the needed extensions are not supported.
  */
 
 #pragma once
@@ -37,6 +40,9 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * Implementation of Multi Draw Indirect using OpenGL.
+ **/
 class GLDrawList : public DrawList {
  public:
   GLDrawList(int length);

source/blender/gpu/opengl/gl_shader.hh

@@ -19,9 +19,6 @@
 
 /** \file
  * \ingroup gpu
- *
- * GPUDrawList is an API to do lots of similar draw-calls very fast using
- * multi-draw-indirect. There is a fallback if the feature is not supported.
  */
 
 #pragma once
@@ -35,6 +32,9 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * Implementation of shader compilation and uniforms handling using OpenGL.
+ **/
 class GLShader : public Shader {
  private:
   /** Handle for full program (links shader stages below). */

source/blender/gpu/opengl/gl_shader_interface.hh

@@ -40,6 +40,9 @@ namespace blender::gpu {
 
 class GLVaoCache;
 
+/**
+ * Implementation of Shader interface using OpenGL.
+ **/
 class GLShaderInterface : public ShaderInterface {
  private:
   /** Reference to VaoCaches using this interface */

source/blender/gpu/opengl/gl_state.hh

@@ -31,6 +31,10 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * State manager keeping track of the draw state and applying it before drawing.
+ * Opengl Implementation.
+ **/
 class GLStateManager : public GPUStateManager {
  private:
   /** Current state of the GL implementation. Avoids resetting the whole state for every change. */

source/blender/gpu/opengl/gl_uniform_buffer.hh

@@ -32,6 +32,9 @@
 namespace blender {
 namespace gpu {
 
+/**
+ * Implementation of Uniform Buffers using OpenGL.
+ **/
 class GLUniformBuf : public UniformBuf {
  private:
   int slot_ = -1;