Add documentation about Image/ImBuf to python/RNA API.

Related to T95616, the relationship between Image ID and ImBuf 'cached'
buffers can be fairly confusing when using the RNA API.

Reviewed By: campbellbarton, jbakker

Differential Revision: https://developer.blender.org/D14833

3 files changed, 35 insertions, 16 deletions

diff --git a/source/blender/makesrna/intern/rna_image.c b/source/blender/makesrna/intern/rna_image.c
index 3a93a44e0d1..bd3b03add95 100644
--- a/source/blender/makesrna/intern/rna_image.c
+++ b/source/blender/makesrna/intern/rna_image.c
@@ -1073,22 +1073,31 @@ static void rna_def_image(BlenderRNA *brna)
   RNA_def_property_ui_text(prop, "Depth", "Image bit depth");
   RNA_def_property_clear_flag(prop, PROP_EDITABLE);
 
-  prop = RNA_def_int_vector(srna,
-                            "size",
-                            2,
-                            NULL,
-                            0,
-                            0,
-                            "Size",
-                            "Width and height in pixels, zero when image data can't be loaded",
-                            0,
-                            0);
+  prop = RNA_def_int_vector(
+      srna,
+      "size",
+      2,
+      NULL,
+      0,
+      0,
+      "Size",
+      "Width and height of the image buffer in pixels, zero when image data can't be loaded",
+      0,
+      0);
   RNA_def_property_subtype(prop, PROP_PIXEL);
   RNA_def_property_int_funcs(prop, "rna_Image_size_get", NULL, NULL);
   RNA_def_property_clear_flag(prop, PROP_EDITABLE);
 
-  prop = RNA_def_float_vector(
-      srna, "resolution", 2, NULL, 0, 0, "Resolution", "X/Y pixels per meter", 0, 0);
+  prop = RNA_def_float_vector(srna,
+                              "resolution",
+                              2,
+                              NULL,
+                              0,
+                              0,
+                              "Resolution",
+                              "X/Y pixels per meter, for the image buffer",
+                              0,
+                              0);
   RNA_def_property_override_flag(prop, PROPOVERRIDE_OVERRIDABLE_LIBRARY);
   RNA_def_property_float_funcs(prop, "rna_Image_resolution_get", "rna_Image_resolution_set", NULL);
 
@@ -1105,7 +1114,7 @@ static void rna_def_image(BlenderRNA *brna)
   prop = RNA_def_property(srna, "pixels", PROP_FLOAT, PROP_NONE);
   RNA_def_property_flag(prop, PROP_DYNAMIC);
   RNA_def_property_multi_array(prop, 1, NULL);
-  RNA_def_property_ui_text(prop, "Pixels", "Image pixels in floating-point values");
+  RNA_def_property_ui_text(prop, "Pixels", "Image buffer pixels in floating-point values");
   RNA_def_property_dynamic_array_funcs(prop, "rna_Image_pixels_get_length");
   RNA_def_property_float_funcs(prop, "rna_Image_pixels_get", "rna_Image_pixels_set", NULL);
 
diff --git a/source/blender/makesrna/intern/rna_image_api.c b/source/blender/makesrna/intern/rna_image_api.c
index 0b188b2b3db..897573f9fd9 100644
--- a/source/blender/makesrna/intern/rna_image_api.c
+++ b/source/blender/makesrna/intern/rna_image_api.c
@@ -316,7 +316,7 @@ void RNA_api_image(StructRNA *srna)
   RNA_def_function_flag(func, FUNC_USE_REPORTS);
 
   func = RNA_def_function(srna, "scale", "rna_Image_scale");
-  RNA_def_function_ui_description(func, "Scale the image in pixels");
+  RNA_def_function_ui_description(func, "Scale the buffer of the image, in pixels");
   RNA_def_function_flag(func, FUNC_USE_REPORTS);
   parm = RNA_def_int(func, "width", 1, 1, INT_MAX, "", "Width", 1, INT_MAX);
   RNA_def_parameter_flags(parm, 0, PARM_REQUIRED);
diff --git a/source/blender/python/generic/imbuf_py_api.c b/source/blender/python/generic/imbuf_py_api.c
index ef11d1ab32d..e6d90c46866 100644
--- a/source/blender/python/generic/imbuf_py_api.c
+++ b/source/blender/python/generic/imbuf_py_api.c
@@ -559,7 +559,11 @@ static PyMethodDef IMB_methods[] = {
     {NULL, NULL, 0, NULL},
 };
 
-PyDoc_STRVAR(IMB_doc, "This module provides access to Blender's image manipulation API.");
+PyDoc_STRVAR(IMB_doc,
+             "This module provides access to Blender's image manipulation API.\n"
+             "\n"
+             "It provides access to image buffers outside of Blender's\n"
+             ":class:`bpy.types.Image` data-block context.\n");
 static struct PyModuleDef IMB_module_def = {
     PyModuleDef_HEAD_INIT,
     "imbuf",     /* m_name */
@@ -596,7 +600,13 @@ PyObject *BPyInit_imbuf(void)
  * for docs and the ability to use with built-ins such as `isinstance`, `issubclass`.
  * \{ */
 
-PyDoc_STRVAR(IMB_types_doc, "This module provides access to image buffer types.");
+PyDoc_STRVAR(IMB_types_doc,
+             "This module provides access to image buffer types.\n"
+             "\n"
+             ".. note::\n"
+             "\n"
+             "   Image buffer is also the structure used by :class:`bpy.types.Image`\n"
+             "   ID type to store and manipulate image data at runtime.\n");
 
 static struct PyModuleDef IMB_types_module_def = {
     PyModuleDef_HEAD_INIT,