forked from bartvdbraak/blender
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
This commit is contained in:
parent
1d9e2dc954
commit
62d64bec2a
2
extern/audaspace/bindings/python/PySound.cpp
vendored
2
extern/audaspace/bindings/python/PySound.cpp
vendored
@ -290,7 +290,7 @@ PyDoc_STRVAR(M_aud_Sound_buffer_doc,
|
||||
".. classmethod:: buffer(data, rate)\n\n"
|
||||
" Creates a sound from a data buffer.\n\n"
|
||||
" :arg data: The data as two dimensional numpy array.\n"
|
||||
" :type data: numpy.ndarray\n"
|
||||
" :type data: :class:`numpy.ndarray`\n"
|
||||
" :arg rate: The sample rate.\n"
|
||||
" :type rate: double\n"
|
||||
" :return: The created :class:`Sound` object.\n"
|
||||
|
@ -67,6 +67,8 @@ def abspath(path, *, start=None, library=None):
|
||||
:arg library: The library this path is from. This is only included for
|
||||
convenience, when the library is not None its path replaces *start*.
|
||||
:type library: :class:`bpy.types.Library`
|
||||
:return: The absolute path.
|
||||
:rtype: string
|
||||
"""
|
||||
if isinstance(path, bytes):
|
||||
if path.startswith(b"//"):
|
||||
@ -101,6 +103,8 @@ def relpath(path, *, start=None):
|
||||
:arg start: Relative to this path,
|
||||
when not set the current filename is used.
|
||||
:type start: string or bytes
|
||||
:return: The relative path.
|
||||
:rtype: string
|
||||
"""
|
||||
if isinstance(path, bytes):
|
||||
if not path.startswith(b"//"):
|
||||
@ -123,6 +127,8 @@ def is_subdir(path, directory):
|
||||
|
||||
:arg path: An absolute path.
|
||||
:type path: string or bytes
|
||||
:return: Whether or not the path is a subdirectory.
|
||||
:rtype: boolean
|
||||
"""
|
||||
from os.path import normpath, normcase, sep
|
||||
path = normpath(normcase(path))
|
||||
@ -141,6 +147,12 @@ def clean_name(name, *, replace="_"):
|
||||
such as writing to a file.
|
||||
All characters besides A-Z/a-z, 0-9 are replaced with "_"
|
||||
or the *replace* argument if defined.
|
||||
:arg name: The path name.
|
||||
:type name: string or bytes
|
||||
:arg replace: The replacement for non-valid characters.
|
||||
:type replace: string
|
||||
:return: The cleaned name.
|
||||
:rtype: string
|
||||
"""
|
||||
|
||||
if replace != "_":
|
||||
@ -207,8 +219,14 @@ def display_name(name, *, has_ext=True, title_case=True):
|
||||
Creates a display string from name to be used menus and the user interface.
|
||||
Intended for use with filenames and module names.
|
||||
|
||||
:arg has_ext: Remove file extension from name
|
||||
:arg title_case: Convert lowercase names to title case
|
||||
:arg name: The name to be used for displaying the user interface.
|
||||
:type name: string
|
||||
:arg has_ext: Remove file extension from name.
|
||||
:type has_ext: boolean
|
||||
:arg title_case: Convert lowercase names to title case.
|
||||
:type title_case: boolean
|
||||
:return: The display string.
|
||||
:rtype: string
|
||||
"""
|
||||
|
||||
if has_ext:
|
||||
@ -233,6 +251,10 @@ def display_name_to_filepath(name):
|
||||
"""
|
||||
Performs the reverse of display_name using literal versions of characters
|
||||
which aren't supported in a filepath.
|
||||
:arg name: The display name to convert.
|
||||
:type name: string
|
||||
:return: The file path.
|
||||
:rtype: string
|
||||
"""
|
||||
for disp_value, file_value in _display_name_literals.items():
|
||||
name = name.replace(disp_value, file_value)
|
||||
@ -243,6 +265,10 @@ def display_name_from_filepath(name):
|
||||
"""
|
||||
Returns the path stripped of directory and extension,
|
||||
ensured to be utf8 compatible.
|
||||
:arg name: The file path to convert.
|
||||
:type name: string
|
||||
:return: The display name.
|
||||
:rtype: string
|
||||
"""
|
||||
|
||||
name = _os.path.splitext(basename(name))[0]
|
||||
@ -254,6 +280,10 @@ def resolve_ncase(path):
|
||||
"""
|
||||
Resolve a case insensitive path on a case sensitive system,
|
||||
returning a string with the path if found else return the original path.
|
||||
:arg path: The path name to resolve.
|
||||
:type path: string
|
||||
:return: The resolved path.
|
||||
:rtype: string
|
||||
"""
|
||||
|
||||
def _ncase_path_found(path):
|
||||
@ -315,11 +345,15 @@ def ensure_ext(filepath, ext, *, case_sensitive=False):
|
||||
"""
|
||||
Return the path with the extension added if it is not already set.
|
||||
|
||||
:arg filepath: The file path.
|
||||
:type filepath: string
|
||||
:arg ext: The extension to check for, can be a compound extension. Should
|
||||
start with a dot, such as '.blend' or '.tar.gz'.
|
||||
:type ext: string
|
||||
:arg case_sensitive: Check for matching case when comparing extensions.
|
||||
:type case_sensitive: bool
|
||||
:type case_sensitive: boolean
|
||||
:return: The file path with the given extension.
|
||||
:rtype: string
|
||||
"""
|
||||
|
||||
if case_sensitive:
|
||||
@ -341,7 +375,7 @@ def module_names(path, *, recursive=False):
|
||||
:arg recursive: Also return submodule names for packages.
|
||||
:type recursive: bool
|
||||
:return: a list of string pairs (module_name, module_file).
|
||||
:rtype: list
|
||||
:rtype: list of strings
|
||||
"""
|
||||
|
||||
from os.path import join, isfile
|
||||
@ -374,6 +408,8 @@ def basename(path):
|
||||
Equivalent to ``os.path.basename``, but skips a "//" prefix.
|
||||
|
||||
Use for Windows compatibility.
|
||||
:return: The base name of the given path.
|
||||
:rtype: string
|
||||
"""
|
||||
return _os.path.basename(path[2:] if path[:2] in {"//", b"//"} else path)
|
||||
|
||||
@ -381,6 +417,10 @@ def basename(path):
|
||||
def native_pathsep(path):
|
||||
"""
|
||||
Replace the path separator with the systems native ``os.sep``.
|
||||
:arg path: The path to replace.
|
||||
:type path: string
|
||||
:return: The path with system native separators.
|
||||
:rtype: string
|
||||
"""
|
||||
if type(path) is str:
|
||||
if _os.sep == "/":
|
||||
@ -407,9 +447,9 @@ def reduce_dirs(dirs):
|
||||
(Useful for recursive path searching).
|
||||
|
||||
:arg dirs: Sequence of directory paths.
|
||||
:type dirs: sequence
|
||||
:type dirs: sequence of strings
|
||||
:return: A unique list of paths.
|
||||
:rtype: list
|
||||
:rtype: list of strings
|
||||
"""
|
||||
dirs = list({_os.path.normpath(_os.path.abspath(d)) for d in dirs})
|
||||
dirs.sort(key=lambda d: len(d))
|
||||
|
@ -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"
|
||||
|
@ -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)
|
||||
|
@ -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"
|
||||
|
@ -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"
|
||||
|
Loading…
Reference in New Issue
Block a user