chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity

Standardize function docstring style in MuJoCo API.

Browse Source 
Updates function comments to consistently use a semicolon (`;`) before describing the return value and to use the imperative form "return" instead of "returns".

Also fix error in docstring of `mjp_registerResourceProvider`

PiperOrigin-RevId: 854888532
Change-Id: I311239a2770ded5febece9958ae4e94c1e522600
This commit is contained in:
Yuval Tassa
2026-01-11 08:59:30 -08:00
committed by Copybara-Service
parent 8abedf263e
commit a26f09accf
3 changed files with 123 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/mujoco/introspect/functions.py
+46 -46
View File
@@ -64,7 +64,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Add file to VFS, return 0: success, 2: repeated name, -1: failed to load.', # pylint: disable=line-too-long
doc='Add file to VFS; return 0: success, 2: repeated name, -1: failed to load.', # pylint: disable=line-too-long
)),
('mj_addBufferVFS',
FunctionDecl(
@@ -94,7 +94,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Add file to VFS from buffer, return 0: success, 2: repeated name, -1: failed to load.', # pylint: disable=line-too-long
doc='Add file to VFS from buffer; return 0: success, 2: repeated name, -1: failed to load.', # pylint: disable=line-too-long
)),
('mj_deleteFileVFS',
FunctionDecl(
@@ -114,7 +114,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Delete file from VFS, return 0: success, -1: not found in VFS.',
doc='Delete file from VFS; return 0: success, -1: not found in VFS.',
)),
('mj_deleteVFS',
FunctionDecl(
@@ -174,7 +174,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='size_t'),
),
),
doc='Set the capacity of the asset cache in bytes (0 to disable); returns the new capacity.', # pylint: disable=line-too-long
doc='Set the capacity of the asset cache in bytes (0 to disable); return the new capacity.', # pylint: disable=line-too-long
)),
('mj_getCache',
FunctionDecl(
@@ -231,7 +231,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Parse XML file in MJCF or URDF format, compile it, return low-level model. If vfs is not NULL, look up files in vfs before reading from disk. If error is not NULL, it must have size error_sz.', # pylint: disable=line-too-long
doc='Parse XML file in MJCF or URDF format, compile it; return low-level model. If vfs is not NULL, look up files in vfs before reading from disk. If error is not NULL, it must have size error_sz.', # pylint: disable=line-too-long
)),
('mj_parseXML',
FunctionDecl(
@@ -382,7 +382,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Copy real-valued arrays from model to spec, returns 1 on success.', # pylint: disable=line-too-long
doc='Copy real-valued arrays from model to spec; return 1 on success.',
)),
('mj_recompile',
FunctionDecl(
@@ -415,7 +415,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Recompile spec to model, preserving the state, return 0 on success.', # pylint: disable=line-too-long
doc='Recompile spec to model, preserving the state; return 0 on success.', # pylint: disable=line-too-long
)),
('mj_saveLastXML',
FunctionDecl(
@@ -488,7 +488,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Save spec to XML string, return 0 on success, -1 on failure. If length of the output buffer is too small, returns the required size.', # pylint: disable=line-too-long
doc='Save spec to XML string; return 0 on success, -1 on failure. If length of the output buffer is too small; return the required size.', # pylint: disable=line-too-long
)),
('mj_saveXML',
FunctionDecl(
@@ -519,7 +519,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Save spec to XML file, return 0 on success, -1 otherwise.',
doc='Save spec to XML file; return 0 on success, -1 otherwise.',
)),
('mju_getXMLDependencies',
FunctionDecl(
@@ -1258,7 +1258,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Activate plugin. Returns 0 on success.',
doc='Activate plugin; return 0 on success.',
)),
('mjs_setDeepCopy',
FunctionDecl(
@@ -1276,7 +1276,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Turn deep copy on or off attach. Returns 0 on success.',
doc='Turn deep copy on or off attach; return 0 on success.',
)),
('mj_printFormattedModel',
FunctionDecl(
@@ -3122,7 +3122,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Get id of object with the specified mjtObj type and name, returns -1 if id not found.', # pylint: disable=line-too-long
doc='Get id of object with the specified mjtObj type and name; return -1 if id not found.', # pylint: disable=line-too-long
)),
('mj_id2name',
FunctionDecl(
@@ -3146,7 +3146,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Get name of object with the specified mjtObj type and id, returns NULL if name not found.', # pylint: disable=line-too-long
doc='Get name of object with the specified mjtObj type and id; return NULL if name not found.', # pylint: disable=line-too-long
)),
('mj_fullM',
FunctionDecl(
@@ -3454,7 +3454,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc='Returns smallest signed distance between two geoms and optionally segment from geom1 to geom2.', # pylint: disable=line-too-long
doc='Return smallest signed distance between two geoms and optionally segment from geom1 to geom2.', # pylint: disable=line-too-long
)),
('mj_contactForce',
FunctionDecl(
@@ -3890,7 +3890,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Intersect ray with hfield, return nearest distance or -1 if no intersection.', # pylint: disable=line-too-long
doc='Intersect ray with hfield; return nearest distance or -1 if no intersection.', # pylint: disable=line-too-long
)),
('mj_rayMesh',
FunctionDecl(
@@ -3928,7 +3928,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Intersect ray with mesh, return nearest distance or -1 if no intersection.', # pylint: disable=line-too-long
doc='Intersect ray with mesh; return nearest distance or -1 if no intersection.', # pylint: disable=line-too-long
)),
('mju_rayGeom',
FunctionDecl(
@@ -3975,7 +3975,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Intersect ray with pure geom, return nearest distance or -1 if no intersection.', # pylint: disable=line-too-long
doc='Intersect ray with pure geom; return nearest distance or -1 if no intersection.', # pylint: disable=line-too-long
)),
('mju_rayFlex',
FunctionDecl(
@@ -4041,7 +4041,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc='Intersect ray with flex, return nearest distance or -1 if no intersection, and also output nearest vertex id.', # pylint: disable=line-too-long
doc='Intersect ray with flex; return nearest distance or -1 if no intersection, and also output nearest vertex id.', # pylint: disable=line-too-long
)),
('mju_raySkin',
FunctionDecl(
@@ -4091,7 +4091,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc='Intersect ray with skin, return nearest distance or -1 if no intersection, and also output nearest vertex id.', # pylint: disable=line-too-long
doc='Intersect ray with skin; return nearest distance or -1 if no intersection, and also output nearest vertex id.', # pylint: disable=line-too-long
)),
('mjv_defaultCamera',
FunctionDecl(
@@ -4640,7 +4640,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc='Select geom, flex or skin with mouse, return bodyid; -1: none selected.', # pylint: disable=line-too-long
doc='Select geom, flex or skin with mouse; return bodyid; -1: none selected.', # pylint: disable=line-too-long
)),
('mjv_defaultOption',
FunctionDecl(
@@ -5879,7 +5879,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Handle UI event, return pointer to changed item, NULL if no change.', # pylint: disable=line-too-long
doc='Handle UI event; return pointer to changed item, NULL if no change.', # pylint: disable=line-too-long
)),
('mjui_render',
FunctionDecl(
@@ -6355,7 +6355,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Normalize vector, return length before normalization.',
doc='Normalize vector; return length before normalization.',
)),
('mju_norm3',
FunctionDecl(
@@ -6568,7 +6568,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Normalize vector, return length before normalization.',
doc='Normalize vector; return length before normalization.',
)),
('mju_zero',
FunctionDecl(
@@ -6884,7 +6884,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Normalize vector, return length before normalization.',
doc='Normalize vector; return length before normalization.',
)),
('mju_norm',
FunctionDecl(
@@ -7024,7 +7024,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc="Multiply square matrix with vectors on both sides: returns vec1' * mat * vec2.", # pylint: disable=line-too-long
doc="Multiply square matrix with vectors on both sides: return vec1' * mat * vec2.", # pylint: disable=line-too-long
)),
('mju_transpose',
FunctionDecl(
@@ -7340,7 +7340,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='int'),
),
),
doc='Convert matrix from dense to sparse. nnz is size of res and colind, return 1 if too small, 0 otherwise.', # pylint: disable=line-too-long
doc='Convert matrix from dense to sparse. nnz is size of res and colind; return 1 if too small, 0 otherwise.', # pylint: disable=line-too-long
)),
('mju_sparse2dense',
FunctionDecl(
@@ -7719,7 +7719,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Extract 3D rotation from an arbitrary 3x3 matrix by refining the input quaternion. Returns the number of iterations required to converge', # pylint: disable=line-too-long
doc='Extract 3D rotation from an arbitrary 3x3 matrix by refining the input quaternion. Return the number of iterations required to converge.', # pylint: disable=line-too-long
)),
('mju_euler2Quat',
FunctionDecl(
@@ -7983,7 +7983,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='mjtNum'),
),
),
doc='Band-dense Cholesky decomposition. Returns minimum value in the factorized diagonal, or 0 if rank-deficient. mat has (ntotal-ndense) x nband + ndense x ntotal elements. The first (ntotal-ndense) x nband store the band part, left of diagonal, inclusive. The second ndense x ntotal store the band part as entire dense rows. Add diagadd+diagmul*mat_ii to diagonal before factorization.', # pylint: disable=line-too-long
doc='Band-dense Cholesky decomposition. Return minimum value in the factorized diagonal, or 0 if rank-deficient. mat has (ntotal-ndense) x nband + ndense x ntotal elements. The first (ntotal-ndense) x nband store the band part, left of diagonal, inclusive. The second ndense x ntotal store the band part as entire dense rows. Add diagadd+diagmul*mat_ii to diagonal before factorization.', # pylint: disable=line-too-long
)),
('mju_cholSolveBand',
FunctionDecl(
@@ -8252,7 +8252,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc="minimize 0.5*x'*H*x + x'*g s.t. lower <= x <= upper, return rank or -1 if failed inputs: n - problem dimension H - SPD matrix n*n g - bias vector n lower - lower bounds n upper - upper bounds n res - solution warmstart n return value: nfree <= n - rank of unconstrained subspace, -1 if failure outputs (required): res - solution n R - subspace Cholesky factor nfree*nfree allocated: n*(n+7) outputs (optional): index - set of free dimensions nfree allocated: n notes: the initial value of res is used to warmstart the solver R must have allocatd size n*(n+7), but only nfree*nfree values are used in output index (if given) must have allocated size n, but only nfree values are used in output only the lower triangles of H and R and are read from and written to, respectively the convenience function mju_boxQPmalloc allocates the required data structures", # pylint: disable=line-too-long
doc="minimize 0.5*x'*H*x + x'*g s.t. lower <= x <= upper; return rank or -1 if failed inputs: n - problem dimension H - SPD matrix n*n g - bias vector n lower - lower bounds n upper - upper bounds n res - solution warmstart n return value: nfree <= n - rank of unconstrained subspace, -1 if failure outputs (required): res - solution n R - subspace Cholesky factor nfree*nfree allocated: n*(n+7) outputs (optional): index - set of free dimensions nfree allocated: n notes: the initial value of res is used to warmstart the solver R must have allocatd size n*(n+7), but only nfree*nfree values are used in output index (if given) must have allocated size n, but only nfree values are used in output only the lower triangles of H and R and are read from and written to, respectively the convenience function mju_boxQPmalloc allocates the required data structures", # pylint: disable=line-too-long
)),
('mju_boxQPmalloc',
FunctionDecl(
@@ -8495,7 +8495,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='mjtNum'),
),
),
doc='Integrate spring-damper analytically, return pos(dt).',
doc='Integrate spring-damper analytically; return pos(dt).',
)),
('mju_min',
FunctionDecl(
@@ -9267,7 +9267,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Globally register a resource provider in a thread-safe manner. The provider must have a prefix that is not a sub-prefix or super-prefix of any current registered providers. This function returns a slot number > 0 on success.', # pylint: disable=line-too-long
doc='Globally register a resource provider in a thread-safe manner. The provider must have a prefix that is not a sub-prefix or super-prefix of any current registered providers. Return a slot number >= 0 on success, -1 on failure.', # pylint: disable=line-too-long
)),
('mjp_resourceProviderCount',
FunctionDecl(
@@ -9484,7 +9484,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Attach child to a parent, return the attached element if success or NULL otherwise.', # pylint: disable=line-too-long
doc='Attach child to a parent; return the attached element if success or NULL otherwise.', # pylint: disable=line-too-long
)),
('mjs_addBody',
FunctionDecl(
@@ -9507,7 +9507,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc='Add child body to body, return child.',
doc='Add child body to body; return child.',
)),
('mjs_addSite',
FunctionDecl(
@@ -9530,7 +9530,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
nullable=True,
),
),
doc='Add site to body, return site spec.',
doc='Add site to body; return site spec.',
)),
('mjs_addJoint',
FunctionDecl(
@@ -9680,7 +9680,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Remove object corresponding to the given element, return 0 on success.', # pylint: disable=line-too-long
doc='Remove object corresponding to the given element; return 0 on success.', # pylint: disable=line-too-long
)),
('mjs_addActuator',
FunctionDecl(
@@ -10041,7 +10041,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Set actuator to motor, return error if any.',
doc='Set actuator to motor; return error if any.',
)),
('mjs_setToPosition',
FunctionDecl(
@@ -10086,7 +10086,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to position, return error if any.',
doc='Set actuator to position; return error if any.',
)),
('mjs_setToIntVelocity',
FunctionDecl(
@@ -10131,7 +10131,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to integrated velocity, return error if any.',
doc='Set actuator to integrated velocity; return error if any.',
)),
('mjs_setToVelocity',
FunctionDecl(
@@ -10151,7 +10151,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to velocity servo, return error if any.',
doc='Set actuator to velocity servo; return error if any.',
)),
('mjs_setToDamper',
FunctionDecl(
@@ -10171,7 +10171,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to activate damper, return error if any.',
doc='Set actuator to activate damper; return error if any.',
)),
('mjs_setToCylinder',
FunctionDecl(
@@ -10203,7 +10203,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to hydraulic or pneumatic cylinder, return error if any.', # pylint: disable=line-too-long
doc='Set actuator to hydraulic or pneumatic cylinder; return error if any.', # pylint: disable=line-too-long
)),
('mjs_setToMuscle',
FunctionDecl(
@@ -10265,7 +10265,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to muscle, return error if any.a',
doc='Set actuator to muscle; return error if any.a',
)),
('mjs_setToAdhesion',
FunctionDecl(
@@ -10285,7 +10285,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
type=ValueType(name='double'),
),
),
doc='Set actuator to active adhesion, return error if any.',
doc='Set actuator to active adhesion; return error if any.',
)),
('mjs_addMesh',
FunctionDecl(
@@ -10809,7 +10809,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc="Set element's name, return 0 on success.",
doc="Set element's name; return 0 on success.",
)),
('mjs_setBuffer',
FunctionDecl(
@@ -11202,7 +11202,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc="Set element's enclosing frame, return 0 on success.",
doc="Set element's enclosing frame; return 0 on success.",
)),
('mjs_resolveOrientation',
FunctionDecl(
@@ -11235,7 +11235,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
),
),
),
doc='Resolve alternative orientations to quat, return error if any.',
doc='Resolve alternative orientations to quat; return error if any.',
)),
('mjs_bodyToFrame',
FunctionDecl(