Py API Docs: Cleanup

5 files changed, 82 insertions, 91 deletions

diff --git a/source/blender/python/gpu/gpu_py_batch.c b/source/blender/python/gpu/gpu_py_batch.c
index add813dd928..77dcfad2c9f 100644
--- a/source/blender/python/gpu/gpu_py_batch.c
+++ b/source/blender/python/gpu/gpu_py_batch.c
@@ -222,10 +222,10 @@ static PyObject *bpygpu_Batch_program_set(BPyGPUBatch *self, BPyGPUShader *py_sh
 PyDoc_STRVAR(bpygpu_Batch_draw_doc,
 ".. method:: draw(program=None)\n"
 "\n"
-"   Run the drawing program with the parameters assigned to the batch.\n"
+"   Run the drawing program with the parameters assigned to the batch. \n"
 "\n"
-"   :param program: program that performs the drawing operations. \n"
-"      If ``None`` is passed, the last program setted to this batch will run.\n"
+"   :param program: Program that performs the drawing operations. \n"
+"      If ``None`` is passed, the last program setted to this batch will run. \n"
 "   :type program: :class:`gpu.types.GPUShader`\n"
 );
 static PyObject *bpygpu_Batch_draw(BPyGPUBatch *self, PyObject *args)
@@ -318,11 +318,11 @@ static void bpygpu_Batch_dealloc(BPyGPUBatch *self)
 }
 
 PyDoc_STRVAR(py_gpu_batch_doc,
-"GPUBatch(type, buf, elem=None)\n"
+".. class:: GPUBatch(type, buf, elem=None)\n"
 "\n"
-"Contains VAOs + VBOs + Shader representing a drawable entity."
+"   Reusable container for drawable geometry. \n"
 "\n"
-"   :param type: One of these primitive types: {\n"
+"   :arg type: One of these primitive types: {\n"
 "       `POINTS`,\n"
 "       `LINES`,\n"
 "       `TRIS`,\n"
@@ -333,10 +333,10 @@ PyDoc_STRVAR(py_gpu_batch_doc,
 "       `LINES_ADJ`,\n"
 "       `TRIS_ADJ`,\n"
 "       `LINE_STRIP_ADJ` }\n"
-"   :type type: :class:`str`\n"
-"   :param buf: Vertex buffer containing all or some of the attributes required for drawing.\n"
+"   :type type: `str`\n"
+"   :arg buf: Vertex buffer containing all or some of the attributes required for drawing.\n"
 "   :type buf: :class:`gpu.types.GPUVertBuf`\n"
-"   :param elem: Optional index buffer.\n"
+"   :arg elem: An optional index buffer.\n"
 "   :type elem: :class:`gpu.types.GPUIndexBuf`\n"
 );
 PyTypeObject BPyGPUBatch_Type = {
diff --git a/source/blender/python/gpu/gpu_py_element.c b/source/blender/python/gpu/gpu_py_element.c
index c85d6dfbe3b..10990abc5e6 100644
--- a/source/blender/python/gpu/gpu_py_element.c
+++ b/source/blender/python/gpu/gpu_py_element.c
@@ -196,20 +196,20 @@ static void bpygpu_IndexBuf_dealloc(BPyGPUIndexBuf *self)
 }
 
 PyDoc_STRVAR(py_gpu_element_doc,
-"GPUIndexBuf(type, seq)\n"
+".. class:: GPUIndexBuf(type, seq)\n"
 "\n"
-"Contains an index buffer."
+"   Contains an index buffer. \n"
 "\n"
-"   :param type:\n"
-"      One of these primitive types: {\n"
+"   :param type: One of these primitive types: {\n"
 "      `POINTS`,\n"
 "      `LINES`,\n"
 "      `TRIS`,\n"
 "      `LINE_STRIP_ADJ` }\n"
-"   :type type: :class:`str`\n"
-"   :param seq: Indices this index buffer will contain.\n"
-"   :type buf: 1D or 2D sequence, depending on the type. \n"
-"              Optionally the sequence can support the buffer protocol. \n"
+"   :type type: `str`\n"
+"   :param seq: Indices this index buffer will contain. \n"
+"       Whether a 1D or 2D sequence is required depends on the type. \n"
+"       Optionally the sequence can support the buffer protocol. \n"
+"   :type seq: 1D or 2D sequence \n"
 );
 PyTypeObject BPyGPUIndexBuf_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
diff --git a/source/blender/python/gpu/gpu_py_offscreen.c b/source/blender/python/gpu/gpu_py_offscreen.c
index 3deeb562b3b..c04dbb48e7d 100644
--- a/source/blender/python/gpu/gpu_py_offscreen.c
+++ b/source/blender/python/gpu/gpu_py_offscreen.c
@@ -102,21 +102,21 @@ static int bpygpu_offscreen_valid_check(BPyGPUOffScreen *bpygpu_ofs)
 	} \
 } ((void)0)
 
-PyDoc_STRVAR(bpygpu_offscreen_width_doc, "Texture width.\n\n:type: int");
+PyDoc_STRVAR(bpygpu_offscreen_width_doc, "Width of the texture.\n\n:type: `int`");
 static PyObject *bpygpu_offscreen_width_get(BPyGPUOffScreen *self, void *UNUSED(type))
 {
 	BPY_GPU_OFFSCREEN_CHECK_OBJ(self);
 	return PyLong_FromLong(GPU_offscreen_width(self->ofs));
 }
 
-PyDoc_STRVAR(bpygpu_offscreen_height_doc, "Texture height.\n\n:type: int");
+PyDoc_STRVAR(bpygpu_offscreen_height_doc, "Height of the texture.\n\n:type: `int`");
 static PyObject *bpygpu_offscreen_height_get(BPyGPUOffScreen *self, void *UNUSED(type))
 {
 	BPY_GPU_OFFSCREEN_CHECK_OBJ(self);
 	return PyLong_FromLong(GPU_offscreen_height(self->ofs));
 }
 
-PyDoc_STRVAR(bpygpu_offscreen_color_texture_doc, "Color texture.\n\n:type: int");
+PyDoc_STRVAR(bpygpu_offscreen_color_texture_doc, "OpenGL bindcode for the color texture.\n\n:type: `int`");
 static PyObject *bpygpu_offscreen_color_texture_get(BPyGPUOffScreen *self, void *UNUSED(type))
 {
 	BPY_GPU_OFFSCREEN_CHECK_OBJ(self);
@@ -125,12 +125,12 @@ static PyObject *bpygpu_offscreen_color_texture_get(BPyGPUOffScreen *self, void
 }
 
 PyDoc_STRVAR(bpygpu_offscreen_bind_doc,
-"bind(save=True)\n"
+".. method:: bind(save=True)\n"
 "\n"
 "   Bind the offscreen object.\n"
 "\n"
-"   :param save: save OpenGL current states.\n"
-"   :type save: bool\n"
+"   :arg save: Save the current OpenGL state, so that it can be restored when unbinding.\n"
+"   :type save: `bool`\n"
 );
 static PyObject *bpygpu_offscreen_bind(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds)
 {
@@ -152,12 +152,12 @@ static PyObject *bpygpu_offscreen_bind(BPyGPUOffScreen *self, PyObject *args, Py
 }
 
 PyDoc_STRVAR(bpygpu_offscreen_unbind_doc,
-"unbind(restore=True)\n"
+".. method:: unbind(restore=True)\n"
 "\n"
 "   Unbind the offscreen object.\n"
 "\n"
-"   :param restore: restore OpenGL previous states.\n"
-"   :type restore: bool\n"
+"   :arg restore: Restore the OpenGL state, can only be used when the state has been saved before.\n"
+"   :type restore: `bool`\n"
 );
 static PyObject *bpygpu_offscreen_unbind(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds)
 {
@@ -179,21 +179,21 @@ static PyObject *bpygpu_offscreen_unbind(BPyGPUOffScreen *self, PyObject *args,
 }
 
 PyDoc_STRVAR(bpygpu_offscreen_draw_view3d_doc,
-"draw_view3d(scene, view3d, region, modelview_matrix, projection_matrix)\n"
+".. method:: draw_view3d(scene, view3d, region, modelview_matrix, projection_matrix)\n"
 "\n"
 "   Draw the 3d viewport in the offscreen object.\n"
 "\n"
-"   :param scene: Scene to draw.\n"
+"   :arg scene: Scene to draw.\n"
 "   :type scene: :class:`bpy.types.Scene`\n"
-"   :param view_layer: View layer to draw.\n"
+"   :arg view_layer: View layer to draw.\n"
 "   :type view_layer: :class:`bpy.types.ViewLayer`\n"
-"   :param view3d: 3D View to get the drawing settings from.\n"
+"   :arg view3d: 3D View to get the drawing settings from.\n"
 "   :type view3d: :class:`bpy.types.SpaceView3D`\n"
-"   :param region: Region of the 3D View.\n"
+"   :arg region: Region of the 3D View (required as temporary draw target).\n"
 "   :type region: :class:`bpy.types.Region`\n"
-"   :param view_matrix: View Matrix.\n"
+"   :arg view_matrix: View Matrix (e.g. ``camera.matrix_world.inverted()``).\n"
 "   :type view_matrix: :class:`mathutils.Matrix`\n"
-"   :param projection_matrix: Projection Matrix.\n"
+"   :arg projection_matrix: Projection Matrix (e.g. ``camera.calc_matrix_camera(...)``).\n"
 "   :type projection_matrix: :class:`mathutils.Matrix`\n"
 );
 static PyObject *bpygpu_offscreen_draw_view3d(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds)
@@ -261,9 +261,9 @@ static PyObject *bpygpu_offscreen_draw_view3d(BPyGPUOffScreen *self, PyObject *a
 }
 
 PyDoc_STRVAR(bpygpu_offscreen_free_doc,
-"free()\n"
+".. method:: free()\n"
 "\n"
-"   Free the offscreen object\n"
+"   Free the offscreen object.\n"
 "   The framebuffer, texture and render objects will no longer be accessible.\n"
 );
 static PyObject *bpygpu_offscreen_free(BPyGPUOffScreen *self)
@@ -298,15 +298,15 @@ static struct PyMethodDef bpygpu_offscreen_methods[] = {
 };
 
 PyDoc_STRVAR(bpygpu_offscreen_doc,
-"GPUOffScreen(width, height, samples=0)\n"
+".. class:: GPUOffScreen(width, height, samples=0)\n"
 "\n"
 "   This object gives access to off screen buffers.\n"
 "\n"
-"   :param width: Horizontal dimension of the buffer.\n"
+"   :arg width: Horizontal dimension of the buffer.\n"
 "   :type width: `int`\n"
-"   :param height: Vertical dimension of the buffer.\n"
+"   :arg height: Vertical dimension of the buffer.\n"
 "   :type height: `int`\n"
-"   :param samples: OpenGL samples to use for MSAA or zero to disable.\n"
+"   :arg samples: OpenGL samples to use for MSAA or zero to disable.\n"
 "   :type samples: `int`\n"
 );
 PyTypeObject BPyGPUOffScreen_Type = {
diff --git a/source/blender/python/gpu/gpu_py_shader.c b/source/blender/python/gpu/gpu_py_shader.c
index 4569e64eb62..19d6c8070f8 100644
--- a/source/blender/python/gpu/gpu_py_shader.c
+++ b/source/blender/python/gpu/gpu_py_shader.c
@@ -145,7 +145,7 @@ static PyObject *bpygpu_shader_new(PyTypeObject *UNUSED(type), PyObject *args, P
 PyDoc_STRVAR(bpygpu_shader_bind_doc,
 ".. method:: bind()\n"
 "\n"
-"   Bind the Shader object.\n"
+"   Bind the shader object. Required to be able to change uniforms of this shader. \n"
 );
 static PyObject *bpygpu_shader_bind(BPyGPUShader *self)
 {
@@ -159,7 +159,7 @@ PyDoc_STRVAR(bpygpu_shader_transform_feedback_enable_doc,
 "   Start transform feedback operation.\n"
 "\n"
 "   :return: true if transform feedback was succesfully enabled.\n"
-"   :rtype: bool\n"
+"   :rtype: `bool`\n"
 );
 static PyObject *bpygpu_shader_transform_feedback_enable(
         BPyGPUShader *self, PyObject *arg)
@@ -187,10 +187,10 @@ PyDoc_STRVAR(bpygpu_shader_uniform_from_name_doc,
 "\n"
 "   Get uniform location by name.\n"
 "\n"
-"   :param name: name of the uniform variable whose location is to be queried.\n"
-"   :type name: str\n"
-"   :return: the location of the uniform variable.\n"
-"   :rtype: int\n"
+"   :param name: Name of the uniform variable whose location is to be queried.\n"
+"   :type name: `str`\n"
+"   :return: Location of the uniform variable.\n"
+"   :rtype: `int`\n"
 );
 static PyObject *bpygpu_shader_uniform_from_name(
         BPyGPUShader *self, PyObject *arg)
@@ -215,10 +215,10 @@ PyDoc_STRVAR(bpygpu_shader_uniform_block_from_name_doc,
 "\n"
 "   Get uniform block location by name.\n"
 "\n"
-"   :param name: name of the uniform block variable whose location is to be queried.\n"
-"   :type name: str\n"
-"   :return: the location of the uniform block variable.\n"
-"   :rtype: int\n"
+"   :param name: Name of the uniform block variable whose location is to be queried.\n"
+"   :type name: `str`\n"
+"   :return: The location of the uniform block variable.\n"
+"   :rtype: `int`\n"
 );
 static PyObject *bpygpu_shader_uniform_block_from_name(
         BPyGPUShader *self, PyObject *arg)
@@ -273,12 +273,11 @@ PyDoc_STRVAR(bpygpu_shader_uniform_vector_float_doc,
 "\n"
 "   Set the buffer to fill the uniform.\n"
 "\n"
-"   :param location: location of the uniform variable to be modified.\n"
+"   :param location: Location of the uniform variable to be modified.\n"
 "   :type location: int\n"
-"   :param buffer: buffer object with format float.\n"
-"   :type buffer: buffer object\n"
-"   :param length:\n"
-"      size of the uniform data type:\n"
+"   :param buffer:  The data that should be set. Can support the buffer protocol.\n"
+"   :type buffer: sequence of floats\n"
+"   :param length: Size of the uniform data type:\n"
 "\n"
 "      - 1: float\n"
 "      - 2: vec2 or float[2]\n"
@@ -288,7 +287,7 @@ PyDoc_STRVAR(bpygpu_shader_uniform_vector_float_doc,
 "      - 16: mat4\n"
 "\n"
 "   :type length: int\n"
-"   :param count: specifies the number of elements, vector or matrices that are to be modified.\n"
+"   :param count: Specifies the number of elements, vector or matrices that are to be modified.\n"
 "   :type count: int\n"
 );
 static PyObject *bpygpu_shader_uniform_vector_float(
@@ -347,9 +346,9 @@ PyDoc_STRVAR(bpygpu_shader_uniform_bool_doc,
 "\n"
 "   Specify the value of a uniform variable for the current program object.\n"
 "\n"
-"   :param name: name of the uniform variable whose location is to be queried.\n"
+"   :param name: Name of the uniform variable whose value is to be changed.\n"
 "   :type name: str\n"
-"   :param seq: values that will be used to update the specified uniform variable.\n"
+"   :param seq: Value that will be used to update the specified uniform variable.\n"
 "   :type seq: sequence of bools\n"
 );
 static PyObject *bpygpu_shader_uniform_bool(
@@ -417,9 +416,9 @@ PyDoc_STRVAR(bpygpu_shader_uniform_float_doc,
 "\n"
 "   Specify the value of a uniform variable for the current program object.\n"
 "\n"
-"   :param name: name of the uniform variable whose location is to be queried.\n"
+"   :param name: Name of the uniform variable whose value is to be changed.\n"
 "   :type name: str\n"
-"   :param value: values that will be used to update the specified uniform variable.\n"
+"   :param value: Value that will be used to update the specified uniform variable.\n"
 "   :type value: single number or sequence of numbers\n"
 );
 static PyObject *bpygpu_shader_uniform_float(
@@ -493,9 +492,9 @@ PyDoc_STRVAR(bpygpu_shader_uniform_int_doc,
 "\n"
 "   Specify the value of a uniform variable for the current program object.\n"
 "\n"
-"   :param name: name of the uniform variable whose location is to be queried.\n"
+"   :param name: name of the uniform variable whose value is to be changed.\n"
 "   :type name: str\n"
-"   :param seq: values that will be used to update the specified uniform variable.\n"
+"   :param seq: Value that will be used to update the specified uniform variable.\n"
 "   :type seq: sequence of numbers\n"
 );
 static PyObject *bpygpu_shader_uniform_int(
@@ -569,9 +568,9 @@ PyDoc_STRVAR(bpygpu_shader_attr_from_name_doc,
 "\n"
 "   Get attribute location by name.\n"
 "\n"
-"   :param name: the name of the attribute variable whose location is to be queried.\n"
+"   :param name: The name of the attribute variable whose location is to be queried.\n"
 "   :type name: str\n"
-"   :return: the location of an attribute variable.\n"
+"   :return: The location of an attribute variable.\n"
 "   :rtype: int\n"
 );
 static PyObject *bpygpu_shader_attr_from_name(
@@ -673,38 +672,30 @@ static void bpygpu_shader_dealloc(BPyGPUShader *self)
 
 
 PyDoc_STRVAR(bpygpu_shader_doc,
-"GPUShader(vertexcode, fragcode, geocode=None, libcode=None, defines=None)\n"
-"\n"
-"GPUShader combines multiple GLSL shaders into a program used for drawing.\n"
-"It must contain a vertex and fragment shaders, with an optional geometry shader.\n"
-"\n"
-"The GLSL #version directive is automatically included at the top of shaders, and set to 330.\n"
-"\n"
-"Some preprocessor directives are automatically added according to the Operating System or availability.\n"
-"\n"
-"These are::\n"
+".. class:: GPUShader(vertexcode, fragcode, geocode=None, libcode=None, defines=None)\n"
 "\n"
-"   \"#define GPU_ATI\\n\"\n"
-"   \"#define GPU_NVIDIA\\n\"\n"
-"   \"#define GPU_INTEL\\n\"\n"
+"   GPUShader combines multiple GLSL shaders into a program used for drawing.\n"
+"   It must contain a vertex and fragment shaders, with an optional geometry shader.\n"
 "\n"
-"The following extensions are enabled by default if supported by the GPU::\n"
+"   The GLSL #version directive is automatically included at the top of shaders, and set to 330.\n"
+"   Some preprocessor directives are automatically added according to the Operating System or availability:\n"
+"   ``GPU_ATI``, ``GPU_NVIDIA`` and ``GPU_INTEL``.\n"
 "\n"
-"   \"#extension GL_ARB_texture_gather: enable\\n\"\n"
-"   \"#extension GL_ARB_texture_query_lod: enable\\n\"\n"
+"   The following extensions are enabled by default if supported by the GPU:\n"
+"   ``GL_ARB_texture_gather`` and ``GL_ARB_texture_query_lod``.\n"
 "\n"
-"To debug shaders, use the --debug-gpu-shaders command line option"
-" to see full GLSL shader compilation and linking errors.\n"
+"   To debug shaders, use the --debug-gpu-shaders command line option"
+"   to see full GLSL shader compilation and linking errors.\n"
 "\n"
-"   :param vertexcode: vertex Shader Code.\n"
+"   :param vertexcode: Vertex shader code.\n"
 "   :type vertexcode: str\n"
-"   :param fragcode: fragment Shader Code.\n"
+"   :param fragcode: Fragment shader code.\n"
 "   :type value: str\n"
-"   :param geocode: geometry Shader Code.\n"
+"   :param geocode: Geometry shader code.\n"
 "   :type value: str\n"
-"   :param libcode: code with functions and presets to be shared between shaders.\n"
+"   :param libcode: Code with functions and presets to be shared between shaders.\n"
 "   :type value: str\n"
-"   :param defines: preprocessor directives.\n"
+"   :param defines: Preprocessor directives.\n"
 "   :type value: str\n"
 );
 PyTypeObject BPyGPUShader_Type = {
diff --git a/source/blender/python/gpu/gpu_py_vertex_buffer.c b/source/blender/python/gpu/gpu_py_vertex_buffer.c
index 1f888597b34..37357fa115c 100644
--- a/source/blender/python/gpu/gpu_py_vertex_buffer.c
+++ b/source/blender/python/gpu/gpu_py_vertex_buffer.c
@@ -246,7 +246,7 @@ static PyObject *bpygpu_VertBuf_new(PyTypeObject *UNUSED(type), PyObject *args,
 }
 
 PyDoc_STRVAR(bpygpu_VertBuf_attr_fill_doc,
-"attr_fill(id, data)\n"
+".. method:: attr_fill(id, data)\n"
 "\n"
 "   Insert data into the buffer for a single attribute.\n"
 "\n"
@@ -311,14 +311,14 @@ static void bpygpu_VertBuf_dealloc(BPyGPUVertBuf *self)
 }
 
 PyDoc_STRVAR(py_gpu_vertex_buffer_doc,
-"GPUVertBuf(len, format)\n"
+".. class:: GPUVertBuf(len, format)\n"
 "\n"
-"Contains a VBO."
+"   Contains a VBO."
 "\n"
-"   :param len: number of elements to allocate\n"
+"   :param len: Amount of vertices that will fit into this buffer.\n"
 "   :type type: `int`\n"
 "   :param format: Vertex format.\n"
-"   :type buf: `gpu.types.GPUVertFormat`\n"
+"   :type buf: :class:`gpu.types.GPUVertFormat`\n"
 );
 PyTypeObject BPyGPUVertBuf_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)