griefith/test
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

PyDoc: use Python's type annotation syntax for doc-strings

Browse Source 
Replace plain-text type information with the type syntax used
for Python's type annotations as it's more concise, especially for
callbacks which often didn't include useful type information.

Note that this change only applies to inline doc-strings,
generated doc-strings from RNA need to be updated separately.

Details:

- Many minor corrections were made when "list" was incorrectly used
  instead of "sequence".
- Some type information wasn't defined in the doc-strings and has been
  added.
- Verbose type info would benefit from support for type aliases.
This commit is contained in:
Campbell Barton
2024-11-03 15:42:19 +11:00
parent 3347aa4017
commit 3bcfb151c1
90 changed files with 722 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
source/blender/python/gpu/gpu_py_buffer.cc
View File

@@ -684,7 +684,7 @@ PyDoc_STRVAR(
" :arg dimensions: Array describing the dimensions.\n"
" :type dimensions: int\n"
" :arg data: Optional data array.\n"
" :type data: sequence\n");
" :type data: Buffer | Sequence[float] | Sequence[int]\n");
PyTypeObject BPyGPU_BufferType = {
/*ob_base*/ PyVarObject_HEAD_INIT(nullptr, 0)
/*tp_name*/ "Buffer",

2
source/blender/python/gpu/gpu_py_capabilities.cc
View File

@@ -247,7 +247,7 @@ PyDoc_STRVAR(
" Get supported extensions in the current context.\n"
"\n"
" :return: Extensions.\n"
" :rtype: tuple of string\n");
" :rtype: tuple[str]\n");
static PyObject *pygpu_extensions_get(PyObject * /*self*/)
{
BPYGPU_IS_INIT_OR_ERROR_OBJ;

2
source/blender/python/gpu/gpu_py_element.cc
View File

@@ -189,7 +189,7 @@ PyDoc_STRVAR(
" :arg 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");
" :type seq: Buffer | Sequence[int] | Sequence[Sequence[int]]\n");
PyTypeObject BPyGPUIndexBuf_Type = {
/*ob_base*/ PyVarObject_HEAD_INIT(nullptr, 0)
/*tp_name*/ "GPUIndexBuf",

13
source/blender/python/gpu/gpu_py_framebuffer.cc
View File

@@ -413,8 +413,8 @@ PyDoc_STRVAR(
" Fill color, depth and stencil textures with specific value.\n"
" Common values: color=(0.0, 0.0, 0.0, 1.0), depth=1.0, stencil=0.\n"
"\n"
" :arg color: float sequence each representing ``(r, g, b, a)``.\n"
" :type color: sequence of 3 or 4 floats\n"
" :arg color: Sequence of 3 or 4 floats representing ``(r, g, b, a)``.\n"
" :type color: Sequence[float]\n"
" :arg depth: depth value.\n"
" :type depth: float\n"
" :arg stencil: stencil value.\n"
@@ -774,6 +774,8 @@ static PyMethodDef pygpu_framebuffer__tp_methods[] = {
# pragma GCC diagnostic pop
#endif
/* Ideally type aliases would de-duplicate: `GPUTexture | dict[str, int | GPUTexture]`
* in this doc-string. */
PyDoc_STRVAR(
/* Wrap. */
pygpu_framebuffer__tp_doc,
@@ -786,10 +788,13 @@ PyDoc_STRVAR(
"\n"
" :arg depth_slot: GPUTexture to attach or a `dict` containing keywords: "
"'texture', 'layer' and 'mip'.\n"
" :type depth_slot: :class:`gpu.types.GPUTexture`, dict or Nonetype\n"
" :type depth_slot: :class:`gpu.types.GPUTexture` | dict[] | None\n"
" :arg color_slots: Tuple where each item can be a GPUTexture or a `dict` "
"containing keywords: 'texture', 'layer' and 'mip'.\n"
" :type color_slots: tuple or Nonetype\n");
" :type color_slots: :class:`gpu.types.GPUTexture` | "
"dict[str, int | :class:`gpu.types.GPUTexture`] | "
"Sequence[:class:`gpu.types.GPUTexture` | dict[str, int | :class:`gpu.types.GPUTexture`]] | "
"None\n");
PyTypeObject BPyGPUFrameBuffer_Type = {
/*ob_base*/ PyVarObject_HEAD_INIT(nullptr, 0)
/*tp_name*/ "GPUFrameBuffer",

8
source/blender/python/gpu/gpu_py_matrix.cc
View File

@@ -370,8 +370,8 @@ PyDoc_STRVAR(
"\n"
" Scale the current stack matrix.\n"
"\n"
" :arg scale: Scale the current stack matrix.\n"
" :type scale: sequence of 2 or 3 floats\n");
" :arg scale: Scale the current stack matrix with 2 or 3 floats.\n"
" :type scale: Sequence[float]\n");
static PyObject *pygpu_matrix_scale(PyObject * /*self*/, PyObject *value)
{
BPYGPU_IS_INIT_OR_ERROR_OBJ;
@@ -419,8 +419,8 @@ PyDoc_STRVAR(
"\n"
" Scale the current stack matrix.\n"
"\n"
" :arg offset: Translate the current stack matrix.\n"
" :type offset: sequence of 2 or 3 floats\n");
" :arg offset: Translate the current stack matrix with 2 or 3 floats.\n"
" :type offset: Sequence[float]\n");
static PyObject *pygpu_matrix_translate(PyObject * /*self*/, PyObject *value)
{
float offset[3];

6
source/blender/python/gpu/gpu_py_offscreen.cc
View File

@@ -322,7 +322,7 @@ PyDoc_STRVAR(
pygpu_offscreen_width_doc,
"Width of the texture.\n"
"\n"
":type: `int`");
":type: int");
static PyObject *pygpu_offscreen_width_get(BPyGPUOffScreen *self, void * /*type*/)
{
BPY_GPU_OFFSCREEN_CHECK_OBJ(self);
@@ -334,7 +334,7 @@ PyDoc_STRVAR(
pygpu_offscreen_height_doc,
"Height of the texture.\n"
"\n"
":type: `int`");
":type: int");
static PyObject *pygpu_offscreen_height_get(BPyGPUOffScreen *self, void * /*type*/)
{
BPY_GPU_OFFSCREEN_CHECK_OBJ(self);
@@ -346,7 +346,7 @@ PyDoc_STRVAR(
pygpu_offscreen_color_texture_doc,
"OpenGL bindcode for the color texture.\n"
"\n"
":type: `int`");
":type: int");
static PyObject *pygpu_offscreen_color_texture_get(BPyGPUOffScreen *self, void * /*type*/)
{
BPY_GPU_OFFSCREEN_CHECK_OBJ(self);

10
source/blender/python/gpu/gpu_py_shader.cc
View File

@@ -261,7 +261,7 @@ PyDoc_STRVAR(
" :arg location: Location of the uniform variable to be modified.\n"
" :type location: int\n"
" :arg buffer: The data that should be set. Can support the buffer protocol.\n"
" :type buffer: sequence of floats\n"
" :type buffer: Sequence[float]\n"
" :arg length: Size of the uniform data type:\n"
"\n"
" - 1: float\n"
@@ -331,7 +331,7 @@ PyDoc_STRVAR(
" :arg name: Name of the uniform variable whose value is to be changed.\n"
" :type name: str\n"
" :arg value: Value that will be used to update the specified uniform variable.\n"
" :type value: bool or sequence of bools\n");
" :type value: bool | Sequence[bool]\n");
static PyObject *pygpu_shader_uniform_bool(BPyGPUShader *self, PyObject *args)
{
const char *error_prefix = "GPUShader.uniform_bool";
@@ -406,7 +406,7 @@ PyDoc_STRVAR(
" :arg name: Name of the uniform variable whose value is to be changed.\n"
" :type name: str\n"
" :arg value: Value that will be used to update the specified uniform variable.\n"
" :type value: single number or sequence of floats\n");
" :type value: float | Sequence[float]\n");
static PyObject *pygpu_shader_uniform_float(BPyGPUShader *self, PyObject *args)
{
const char *error_prefix = "GPUShader.uniform_float";
@@ -478,7 +478,7 @@ PyDoc_STRVAR(
" :arg name: name of the uniform variable whose value is to be changed.\n"
" :type name: str\n"
" :arg seq: Value that will be used to update the specified uniform variable.\n"
" :type seq: sequence of ints\n");
" :type seq: Sequence[int]\n");
static PyObject *pygpu_shader_uniform_int(BPyGPUShader *self, PyObject *args)
{
const char *error_prefix = "GPUShader.uniform_int";
@@ -689,7 +689,7 @@ PyDoc_STRVAR(
" Information about the attributes used in the Shader.\n"
"\n"
" :return: tuples containing information about the attributes in order (name, type)\n"
" :rtype: tuple\n");
" :rtype: tuple[tuple[str, str | None], ...]\n");
static PyObject *pygpu_shader_attrs_info_get(BPyGPUShader *self, PyObject * /*arg*/)
{
uint attr_len = GPU_shader_get_attribute_len(self->shader);

7
source/blender/python/gpu/gpu_py_shader_create_info.cc
View File

@@ -692,7 +692,7 @@ PyDoc_STRVAR(
"read or written. Possible values are:\n"
"" PYDOC_QUALIFIERS
""
" :type qualifiers: set\n");
" :type qualifiers: set[str]\n");
static PyObject *pygpu_shader_info_image(BPyGPUShaderCreateInfo *self,
PyObject *args,
PyObject *kwds)
@@ -891,9 +891,8 @@ PyDoc_STRVAR(
" :type type: str\n"
" :arg name: Name of the constant.\n"
" :type name: str\n"
" :arg size: If not zero, indicates that the constant is an array with the "
"specified size.\n"
" :type size: uint\n");
" :arg size: If not zero, indicates that the constant is an array with the specified size.\n"
" :type size: int\n");
static PyObject *pygpu_shader_info_push_constant(BPyGPUShaderCreateInfo *self,
PyObject *args,
PyObject *kwds)

2
source/blender/python/gpu/gpu_py_state.cc
View File

@@ -301,7 +301,7 @@ PyDoc_STRVAR(
" (x, y, xsize, ysize).\n"
" x, y: lower left corner of the scissor rectangle, in pixels.\n"
" xsize, ysize: width and height of the scissor rectangle.\n"
" :rtype: tuple(int, int, int, int)\n");
" :rtype: tuple[int, int, int, int]\n");
static PyObject *pygpu_state_scissor_get(PyObject * /*self*/, PyObject * /*args*/)
{
BPYGPU_IS_INIT_OR_ERROR_OBJ;

12
source/blender/python/gpu/gpu_py_texture.cc
View File

@@ -295,7 +295,7 @@ PyDoc_STRVAR(
pygpu_texture_width_doc,
"Width of the texture.\n"
"\n"
":type: `int`");
":type: int");
static PyObject *pygpu_texture_width_get(BPyGPUTexture *self, void * /*type*/)
{
BPYGPU_TEXTURE_CHECK_OBJ(self);
@@ -307,7 +307,7 @@ PyDoc_STRVAR(
pygpu_texture_height_doc,
"Height of the texture.\n"
"\n"
":type: `int`");
":type: int");
static PyObject *pygpu_texture_height_get(BPyGPUTexture *self, void * /*type*/)
{
BPYGPU_TEXTURE_CHECK_OBJ(self);
@@ -319,7 +319,7 @@ PyDoc_STRVAR(
pygpu_texture_format_doc,
"Format of the texture.\n"
"\n"
":type: `str`");
":type: str");
static PyObject *pygpu_texture_format_get(BPyGPUTexture *self, void * /*type*/)
{
BPYGPU_TEXTURE_CHECK_OBJ(self);
@@ -337,8 +337,8 @@ PyDoc_STRVAR(
" :arg format: The format that describes the content of a single item.\n"
" Possible values are `FLOAT`, `INT`, `UINT`, `UBYTE`, `UINT_24_8` and `10_11_11_REV`.\n"
" :type format: str\n"
" :arg value: sequence each representing the value to fill.\n"
" :type value: sequence of 1, 2, 3 or 4 values\n");
" :arg value: Sequence each representing the value to fill. Sizes 1..4 are supported.\n"
" :type value: Sequence[float]\n");
static PyObject *pygpu_texture_clear(BPyGPUTexture *self, PyObject *args, PyObject *kwds)
{
BPYGPU_TEXTURE_CHECK_OBJ(self);
@@ -540,7 +540,7 @@ PyDoc_STRVAR(
" This object gives access to off GPU textures.\n"
"\n"
" :arg size: Dimensions of the texture 1D, 2D, 3D or cubemap.\n"
" :type size: tuple or int\n"
" :type size: int | Sequence[int]\n"
" :arg layers: Number of layers in texture array or number of cubemaps in cubemap array\n"
" :type layers: int\n"
" :arg is_cubemap: Indicates the creation of a cubemap texture.\n"

7
source/blender/python/gpu/gpu_py_vertex_buffer.cc
View File

@@ -270,9 +270,10 @@ PyDoc_STRVAR(
" Insert data into the buffer for a single attribute.\n"
"\n"
" :arg id: Either the name or the id of the attribute.\n"
" :type id: int or str\n"
" :arg data: Sequence of data that should be stored in the buffer\n"
" :type data: sequence of floats, ints, vectors or matrices\n");
" :type id: int | str\n"
" :arg data: Buffer or sequence of data that should be stored in the buffer\n"
" :type data: Buffer | "
"Sequence[float] | Sequence[int] | Sequence[Sequence[float]] | Sequence[Sequence[int]]\n");
static PyObject *pygpu_vertbuf_attr_fill(BPyGPUVertBuf *self, PyObject *args, PyObject *kwds)
{
PyObject *data;