Cleanup: move public doc-strings into headers for 'gpu'

Ref T92709

1 files changed, 22 insertions, 2 deletions

diff --git a/source/blender/gpu/GPU_state.h b/source/blender/gpu/GPU_state.h
index 1c1211d2a3e..fa70a8934db 100644
--- a/source/blender/gpu/GPU_state.h
+++ b/source/blender/gpu/GPU_state.h
@@ -48,8 +48,8 @@ ENUM_OPERATORS(eGPUBarrier, GPU_BARRIER_SHADER_STORAGE)
  * Defines the fixed pipeline blending equation.
  * SRC is the output color from the shader.
  * DST is the color from the frame-buffer.
- * The blending equation is :
- *  (SRC * A) + (DST * B).
+ * The blending equation is:
+ * `(SRC * A) + (DST * B)`.
  * The blend mode will modify the A and B parameters.
  */
 typedef enum eGPUBlend {
@@ -124,10 +124,23 @@ void GPU_front_facing(bool invert);
 void GPU_depth_range(float near, float far);
 void GPU_scissor_test(bool enable);
 void GPU_line_smooth(bool enable);
+/**
+ * \note By convention, this is set as needed and not reset back to 1.0.
+ * This means code that draws lines must always set the line width beforehand,
+ * but is not expected to restore it's previous value.
+ */
 void GPU_line_width(float width);
 void GPU_logic_op_xor_set(bool enable);
 void GPU_point_size(float size);
 void GPU_polygon_smooth(bool enable);
+
+/**
+ * Programmable point size:
+ * - Shaders set their own point size when enabled
+ * - Use GPU_point_size when disabled.
+ *
+ * TODO: remove and use program point size everywhere.
+ */
 void GPU_program_point_size(bool enable);
 void GPU_scissor(int x, int y, int width, int height);
 void GPU_scissor_get(int coords[4]);
@@ -158,6 +171,9 @@ eGPUDepthTest GPU_depth_test_get(void);
 eGPUWriteMask GPU_write_mask_get(void);
 uint GPU_stencil_mask_get(void);
 eGPUStencilTest GPU_stencil_test_get(void);
+/**
+ * \note Already pre-multiplied by `U.pixelsize`.
+ */
 float GPU_line_width_get(void);
 
 void GPU_flush(void);
@@ -165,6 +181,10 @@ void GPU_finish(void);
 void GPU_apply_state(void);
 
 void GPU_bgl_start(void);
+
+/**
+ * Just turn off the `bgl` safeguard system. Can be called even without #GPU_bgl_start.
+ */
 void GPU_bgl_end(void);
 bool GPU_bgl_get(void);