From 62d64bec2a9c14c5d1515350cfc6b524118058c2 Mon Sep 17 00:00:00 2001
From: Xavier Cho <mysticfall>
Date: Fri, 22 Oct 2021 18:27:03 -0400
Subject: Docs: Fixes and improvements in API documentation

Fixes several notable mistakes and missing information
regarding the API documentation (*.rst).

This will allow API stub generators like bpystubgen or
fake-bpy-module to produce more accurate result.

Differential Revision: https://developer.blender.org/D12639
---
 source/blender/python/generic/bl_math_py_api.c    | 22 +++++++++++-----------
 source/blender/python/gpu/gpu_py_texture.c        |  2 +-
 source/blender/python/intern/bpy_rna.c            |  4 ++--
 source/blender/python/mathutils/mathutils_noise.c |  2 +-
 4 files changed, 15 insertions(+), 15 deletions(-)

(limited to 'source/blender/python')

diff --git a/source/blender/python/generic/bl_math_py_api.c b/source/blender/python/generic/bl_math_py_api.c
index f17aaa4ca5d..5e938db0c35 100644
--- a/source/blender/python/generic/bl_math_py_api.c
+++ b/source/blender/python/generic/bl_math_py_api.c
@@ -77,14 +77,14 @@ static PyObject *py_bl_math_clamp(PyObject *UNUSED(self), PyObject *args)
 }
 
 PyDoc_STRVAR(py_bl_math_lerp_doc,
-             ".. function:: lerp(from, to, factor)\n"
+             ".. function:: lerp(from_value, to_value, factor)\n"
              "\n"
              "   Linearly interpolate between two float values based on factor.\n"
              "\n"
-             "   :arg from: The value to return when factor is 0.\n"
-             "   :type from: float\n"
-             "   :arg to: The value to return when factor is 1.\n"
-             "   :type to: float\n"
+             "   :arg from_value: The value to return when factor is 0.\n"
+             "   :type from_value: float\n"
+             "   :arg to_value: The value to return when factor is 1.\n"
+             "   :type to_value: float\n"
              "   :arg factor: The interpolation value, normally in [0.0, 1.0].\n"
              "   :type factor: float\n"
              "   :return: The interpolated value.\n"
@@ -101,15 +101,15 @@ static PyObject *py_bl_math_lerp(PyObject *UNUSED(self), PyObject *args)
 
 PyDoc_STRVAR(
     py_bl_math_smoothstep_doc,
-    ".. function:: smoothstep(from, to, value)\n"
+    ".. function:: smoothstep(from_value, to_value, value)\n"
     "\n"
-    "   Performs smooth interpolation between 0 and 1 as value changes between from and to.\n"
+    "   Performs smooth interpolation between 0 and 1 as value changes between from and to values.\n"
     "   Outside the range the function returns the same value as the nearest edge.\n"
     "\n"
-    "   :arg from: The edge value where the result is 0.\n"
-    "   :type from: float\n"
-    "   :arg to: The edge value where the result is 1.\n"
-    "   :type to: float\n"
+    "   :arg from_value: The edge value where the result is 0.\n"
+    "   :type from_value: float\n"
+    "   :arg to_value: The edge value where the result is 1.\n"
+    "   :type to_value: float\n"
     "   :arg factor: The interpolation value.\n"
     "   :type factor: float\n"
     "   :return: The interpolated value in [0.0, 1.0].\n"
diff --git a/source/blender/python/gpu/gpu_py_texture.c b/source/blender/python/gpu/gpu_py_texture.c
index 5d136921300..c034c31d828 100644
--- a/source/blender/python/gpu/gpu_py_texture.c
+++ b/source/blender/python/gpu/gpu_py_texture.c
@@ -536,7 +536,7 @@ PyDoc_STRVAR(pygpu_texture_from_image_doc,
              "premultiplied or straight alpha matching the image alpha mode.\n"
              "\n"
              "   :arg image: The Image datablock.\n"
-             "   :type image: `bpy.types.Image`\n"
+             "   :type image: :class:`bpy.types.Image`\n"
              "   :return: The GPUTexture used by the image.\n"
              "   :rtype: :class:`gpu.types.GPUTexture`\n");
 static PyObject *pygpu_texture_from_image(PyObject *UNUSED(self), PyObject *arg)
diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c
index 1296a6c174c..7b1877f3191 100644
--- a/source/blender/python/intern/bpy_rna.c
+++ b/source/blender/python/intern/bpy_rna.c
@@ -8786,7 +8786,7 @@ void pyrna_free_types(void)
  * - Should still be fixed - Campbell
  */
 PyDoc_STRVAR(pyrna_register_class_doc,
-             ".. method:: register_class(cls)\n"
+             ".. function:: register_class(cls)\n"
              "\n"
              "   Register a subclass of a Blender type class.\n"
              "\n"
@@ -8971,7 +8971,7 @@ static int pyrna_srna_contains_pointer_prop_srna(StructRNA *srna_props,
 }
 
 PyDoc_STRVAR(pyrna_unregister_class_doc,
-             ".. method:: unregister_class(cls)\n"
+             ".. function:: unregister_class(cls)\n"
              "\n"
              "   Unload the Python class from blender.\n"
              "\n"
diff --git a/source/blender/python/mathutils/mathutils_noise.c b/source/blender/python/mathutils/mathutils_noise.c
index 69d37b345c6..d5e27496af8 100644
--- a/source/blender/python/mathutils/mathutils_noise.c
+++ b/source/blender/python/mathutils/mathutils_noise.c
@@ -562,7 +562,7 @@ PyDoc_STRVAR(M_Noise_turbulence_vector_doc,
              "   :type octaves: int\n"
              "   :arg hard: Specifies whether returned turbulence is hard (sharp transitions) or "
              "soft (smooth transitions).\n"
-             "   :type hard: :boolean\n" BPY_NOISE_BASIS_ENUM_DOC
+             "   :type hard: boolean\n" BPY_NOISE_BASIS_ENUM_DOC
              "   :arg amplitude_scale: The amplitude scaling factor.\n"
              "   :type amplitude_scale: float\n"
              "   :arg frequency_scale: The frequency scaling factor\n"
-- 
cgit v1.2.3