Tag nullable arguments in main header. Fixes #309

Nullable arguments will be added to the `introspect` datastructures in a future change.

PiperOrigin-RevId: 789350522
Change-Id: I0bfd12fab5121f94b937264570f907593b63cf64

include/mujoco/mujoco.h

@@ -96,25 +96,31 @@ MJAPI void mj_deleteVFS(mjVFS* vfs);
 // 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.
+// Nullable: vfs, error
 MJAPI mjModel* mj_loadXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
 
 // Parse spec from XML file.
+// Nullable: vfs, error
 MJAPI mjSpec* mj_parseXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
 
 // Parse spec from XML string.
+// Nullable: vfs, error
 MJAPI mjSpec* mj_parseXMLString(const char* xml, const mjVFS* vfs, char* error, int error_sz);
 
 // Compile spec to model.
+// Nullable: vfs
 MJAPI mjModel* mj_compile(mjSpec* s, const mjVFS* vfs);
 
 // Copy real-valued arrays from model to spec, returns 1 on success.
 MJAPI int mj_copyBack(mjSpec* s, const mjModel* m);
 
 // Recompile spec to model, preserving the state, return 0 on success.
+// Nullable: vfs
 MJAPI int mj_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d);
 
 // Update XML data structures with info from low-level model created with mj_loadXML, save as MJCF.
 // If error is not NULL, it must have size error_sz.
+// Nullable: error
 MJAPI int mj_saveLastXML(const char* filename, const mjModel* m, char* error, int error_sz);
 
 // Free last XML model if loaded. Called internally at each load.
@@ -122,9 +128,11 @@ MJAPI void mj_freeLastXML(void);
 
 // 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.
+// Nullable: error
 MJAPI int mj_saveXMLString(const mjSpec* s, char* xml, int xml_sz, char* error, int error_sz);
 
 // Save spec to XML file, return 0 on success, -1 otherwise.
+// Nullable: error
 MJAPI int mj_saveXML(const mjSpec* s, const char* filename, char* error, int error_sz);
 
 
@@ -170,10 +178,12 @@ MJAPI void mj_defaultVisual(mjVisual* vis);
 MJAPI mjModel* mj_copyModel(mjModel* dest, const mjModel* src);
 
 // Save model to binary MJB file or memory buffer; buffer has precedence when given.
+// Nullable: filename, buffer
 MJAPI void mj_saveModel(const mjModel* m, const char* filename, void* buffer, int buffer_sz);
 
 // Load model from binary MJB file.
 // If vfs is not NULL, look up file in vfs before reading from disk.
+// Nullable: vfs
 MJAPI mjModel* mj_loadModel(const char* filename, const mjVFS* vfs);
 
 // Free memory allocation in model.
@@ -233,6 +243,7 @@ MJAPI void mj_resetCallbacks(void);
 MJAPI void mj_setConst(mjModel* m, mjData* d);
 
 // Set actuator_lengthrange for specified actuator; return 1 if ok, 0 if error.
+// Nullable: error
 MJAPI int mj_setLengthRange(mjModel* m, mjData* d, int index,
                             const mjLROpt* opt, char* error, int error_sz);
 
@@ -412,6 +423,7 @@ MJAPI void mj_referenceConstraint(const mjModel* m, mjData* d);
 
 // Compute efc_state, efc_force, qfrc_constraint, and (optionally) cone Hessians.
 // If cost is not NULL, set *cost = s(jar) where jar = Jac*qacc-aref.
+// Nullable: cost
 MJAPI void mj_constraintUpdate(const mjModel* m, mjData* d, const mjtNum* jar,
                                mjtNum cost[1], int flg_coneHessian);
 
@@ -449,29 +461,36 @@ MJAPI void mj_mulJacVec(const mjModel* m, const mjData* d, mjtNum* res, const mj
 MJAPI void mj_mulJacTVec(const mjModel* m, const mjData* d, mjtNum* res, const mjtNum* vec);
 
 // Compute 3/6-by-nv end-effector Jacobian of global point attached to given body.
+// Nullable: jacp, jacr
 MJAPI void mj_jac(const mjModel* m, const mjData* d, mjtNum* jacp, mjtNum* jacr,
                   const mjtNum point[3], int body);
 
 // Compute body frame end-effector Jacobian.
+// Nullable: jacp, jacr
 MJAPI void mj_jacBody(const mjModel* m, const mjData* d, mjtNum* jacp, mjtNum* jacr, int body);
 
 // Compute body center-of-mass end-effector Jacobian.
+// Nullable: jacp, jacr
 MJAPI void mj_jacBodyCom(const mjModel* m, const mjData* d, mjtNum* jacp, mjtNum* jacr, int body);
 
 // Compute subtree center-of-mass end-effector Jacobian.
 MJAPI void mj_jacSubtreeCom(const mjModel* m, mjData* d, mjtNum* jacp, int body);
 
 // Compute geom end-effector Jacobian.
+// Nullable: jacp, jacr
 MJAPI void mj_jacGeom(const mjModel* m, const mjData* d, mjtNum* jacp, mjtNum* jacr, int geom);
 
 // Compute site end-effector Jacobian.
+// Nullable: jacp, jacr
 MJAPI void mj_jacSite(const mjModel* m, const mjData* d, mjtNum* jacp, mjtNum* jacr, int site);
 
 // Compute translation end-effector Jacobian of point, and rotation Jacobian of axis.
+// Nullable: jacPoint, jacAxis
 MJAPI void mj_jacPointAxis(const mjModel* m, mjData* d, mjtNum* jacPoint, mjtNum* jacAxis,
                            const mjtNum point[3], const mjtNum axis[3], int body);
 
 // Compute 3/6-by-nv Jacobian time derivative of global point attached to given body.
+// Nullable: jacp, jacr
 MJAPI void mj_jacDot(const mjModel* m, const mjData* d, mjtNum* jacp, mjtNum* jacr,
                      const mjtNum point[3], int body);
 
@@ -495,9 +514,11 @@ MJAPI void mj_mulM2(const mjModel* m, const mjData* d, mjtNum* res, const mjtNum
 
 // Add inertia matrix to destination matrix.
 // Destination can be sparse or dense when all int* are NULL.
+// Nullable: rownnz, rowadr, colind
 MJAPI void mj_addM(const mjModel* m, mjData* d, mjtNum* dst, int* rownnz, int* rowadr, int* colind);
 
 // Apply Cartesian force and torque (outside xfrc_applied mechanism).
+// Nullable: force, torque
 MJAPI void mj_applyFT(const mjModel* m, mjData* d, const mjtNum force[3], const mjtNum torque[3],
                       const mjtNum point[3], int body, mjtNum* qfrc_target);
 
@@ -510,6 +531,7 @@ MJAPI void mj_objectAcceleration(const mjModel* m, const mjData* d,
                                  int objtype, int objid, mjtNum res[6], int flg_local);
 
 // Returns smallest signed distance between two geoms and optionally segment from geom1 to geom2.
+// Nullable: fromto
 MJAPI mjtNum mj_geomDistance(const mjModel* m, const mjData* d, int geom1, int geom2,
                              mjtNum distmax, mjtNum fromto[6]);
 
@@ -566,6 +588,7 @@ MJAPI void mj_multiRay(const mjModel* m, mjData* d, const mjtNum pnt[3], const m
 // Intersect ray (pnt+x*vec, x>=0) with visible geoms, except geoms in bodyexclude.
 // Return distance (x) to nearest surface, or -1 if no intersection and output geomid.
 // geomgroup, flg_static are as in mjvOption; geomgroup==NULL skips group exclusion.
+// Nullable: geomid
 MJAPI mjtNum mj_ray(const mjModel* m, const mjData* d, const mjtNum pnt[3], const mjtNum vec[3],
                     const mjtByte* geomgroup, mjtByte flg_static, int bodyexclude,
                     int geomid[1]);
@@ -584,12 +607,14 @@ MJAPI mjtNum mju_rayGeom(const mjtNum pos[3], const mjtNum mat[9], const mjtNum
 
 // Intersect ray with flex, return nearest distance or -1 if no intersection,
 // and also output nearest vertex id.
+// Nullable: vertid
 MJAPI mjtNum mju_rayFlex(const mjModel* m, const mjData* d, int flex_layer, mjtByte flg_vert,
                          mjtByte flg_edge, mjtByte flg_face, mjtByte flg_skin, int flexid,
                          const mjtNum* pnt, const mjtNum* vec, int vertid[1]);
 
 // Intersect ray with skin, return nearest distance or -1 if no intersection,
 // and also output nearest vertex id.
+// Nullable: vertid
 MJAPI mjtNum mju_raySkin(int nface, int nvert, const int* face, const float* vert,
                          const mjtNum pnt[3], const mjtNum vec[3], int vertid[1]);
 
@@ -654,6 +679,7 @@ MJAPI void mjv_applyPerturbForce(const mjModel* m, mjData* d, const mjvPerturb*
 MJAPI mjvGLCamera mjv_averageCamera(const mjvGLCamera* cam1, const mjvGLCamera* cam2);
 
 // Select geom, flex or skin with mouse, return bodyid; -1: none selected.
+// Nullable: geomid, flexid, skinid
 MJAPI int mjv_select(const mjModel* m, const mjData* d, const mjvOption* vopt,
                      mjtNum aspectratio, mjtNum relx, mjtNum rely,
                      const mjvScene* scn, mjtNum selpnt[3],
@@ -669,6 +695,7 @@ MJAPI void mjv_defaultOption(mjvOption* opt);
 MJAPI void mjv_defaultFigure(mjvFigure* fig);
 
 // Initialize given geom fields when not NULL, set the rest to their default values.
+// Nullable: size, pos, mat, rgba
 MJAPI void mjv_initGeom(mjvGeom* geom, int type, const mjtNum size[3],
                         const mjtNum pos[3], const mjtNum mat[9], const float rgba[4]);
 
@@ -692,6 +719,7 @@ MJAPI void mjv_updateScene(const mjModel* m, mjData* d, const mjvOption* opt,
                            const mjvPerturb* pert, mjvCamera* cam, int catmask, mjvScene* scn);
 
 // Copy mjModel, skip large arrays not required for abstract visualization.
+// Nullable: dest
 MJAPI void mjv_copyModel(mjModel* dest, const mjModel* src);
 
 // Add geoms from selected categories.
@@ -1050,6 +1078,7 @@ MJAPI void mju_sqrMatTD(mjtNum* res, const mjtNum* mat, const mjtNum* diag, int
 
 // Coordinate transform of 6D motion or force vector in rotation:translation format.
 // rotnew2old is 3-by-3, NULL means no rotation; flg_force specifies force or motion type.
+// Nullable: rotnew2old
 MJAPI void mju_transformSpatial(mjtNum res[6], const mjtNum vec[6], int flg_force,
                                 const mjtNum newpos[3], const mjtNum oldpos[3],
                                 const mjtNum rotnew2old[9]);
@@ -1192,6 +1221,7 @@ MJAPI int mju_eig3(mjtNum eigval[3], mjtNum eigvec[9], mjtNum quat[4], const mjt
 //     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
+// Nullable: index, lower, upper
 MJAPI int mju_boxQP(mjtNum* res, mjtNum* R, int* index, const mjtNum* H, const mjtNum* g, int n,
                     const mjtNum* lower, const mjtNum* upper);
 
@@ -1311,6 +1341,7 @@ MJAPI void mjc_gradient(const mjModel* m, const mjData* d, const mjSDF* s, mjtNu
 //      B: (2*nv+na x nu)
 //      D: (nsensordata x 2*nv+na)
 //      C: (nsensordata x nu)
+// Nullable: A, B, C, D
 MJAPI void mjd_transitionFD(const mjModel* m, mjData* d, mjtNum eps, mjtByte flg_centered,
                             mjtNum* A, mjtNum* B, mjtNum* C, mjtNum* D);
 
@@ -1329,15 +1360,18 @@ MJAPI void mjd_transitionFD(const mjModel* m, mjData* d, mjtNum eps, mjtByte flg
 //   notes:
 //     optionally computes mass matrix Jacobian DmDq
 //     flg_actuation specifies whether to subtract qfrc_actuator from qfrc_inverse
+// Nullable: DfDq, DfDv, DfDa, DsDq, DsDv, DsDa, DmDq
 MJAPI void mjd_inverseFD(const mjModel* m, mjData* d, mjtNum eps, mjtByte flg_actuation,
                          mjtNum *DfDq, mjtNum *DfDv, mjtNum *DfDa,
                          mjtNum *DsDq, mjtNum *DsDv, mjtNum *DsDa,
                          mjtNum *DmDq);
 
 // Derivatives of mju_subQuat.
+// Nullable: Da, Db
 MJAPI void mjd_subQuat(const mjtNum qa[4], const mjtNum qb[4], mjtNum Da[9], mjtNum Db[9]);
 
 // Derivatives of mju_quatIntegrate.
+// Nullable: Dquat, Dvel, Dscale
 MJAPI void mjd_quatIntegrate(const mjtNum vel[3], mjtNum scale,
                              mjtNum Dquat[9], mjtNum Dvel[9], mjtNum Dscale[3]);
 
@@ -1415,24 +1449,30 @@ MJAPI mjsElement* mjs_attach(mjsElement* parent, const mjsElement* child,
 //---------------------------------- Tree elements -------------------------------------------------
 
 // Add child body to body, return child.
+// Nullable: def
 MJAPI mjsBody* mjs_addBody(mjsBody* body, const mjsDefault* def);
 
 // Add site to body, return site spec.
+// Nullable: def
 MJAPI mjsSite* mjs_addSite(mjsBody* body, const mjsDefault* def);
 
 // Add joint to body.
+// Nullable: def
 MJAPI mjsJoint* mjs_addJoint(mjsBody* body, const mjsDefault* def);
 
 // Add freejoint to body.
 MJAPI mjsJoint* mjs_addFreeJoint(mjsBody* body);
 
 // Add geom to body.
+// Nullable: def
 MJAPI mjsGeom* mjs_addGeom(mjsBody* body, const mjsDefault* def);
 
 // Add camera to body.
+// Nullable: def
 MJAPI mjsCamera* mjs_addCamera(mjsBody* body, const mjsDefault* def);
 
 // Add light to body.
+// Nullable: def
 MJAPI mjsLight* mjs_addLight(mjsBody* body, const mjsDefault* def);
 
 // Add frame to body.
@@ -1445,6 +1485,7 @@ MJAPI int mjs_delete(mjSpec* spec, mjsElement* element);
 //---------------------------------- Non-tree elements ---------------------------------------------
 
 // Add actuator.
+// Nullable: def
 MJAPI mjsActuator* mjs_addActuator(mjSpec* s, const mjsDefault* def);
 
 // Add sensor.
@@ -1454,15 +1495,18 @@ MJAPI mjsSensor* mjs_addSensor(mjSpec* s);
 MJAPI mjsFlex* mjs_addFlex(mjSpec* s);
 
 // Add contact pair.
+// Nullable: def
 MJAPI mjsPair* mjs_addPair(mjSpec* s, const mjsDefault* def);
 
 // Add excluded body pair.
 MJAPI mjsExclude* mjs_addExclude(mjSpec* s);
 
 // Add equality.
+// Nullable: def
 MJAPI mjsEquality* mjs_addEquality(mjSpec* s, const mjsDefault* def);
 
 // Add tendon.
+// Nullable: def
 MJAPI mjsTendon* mjs_addTendon(mjSpec* s, const mjsDefault* def);
 
 // Wrap site using tendon.
@@ -1493,6 +1537,7 @@ MJAPI mjsKey* mjs_addKey(mjSpec* s);
 MJAPI mjsPlugin* mjs_addPlugin(mjSpec* s);
 
 // Add default.
+// Nullable: parent
 MJAPI mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, const mjsDefault* parent);
 
 
@@ -1531,6 +1576,7 @@ MJAPI const char* mjs_setToAdhesion(mjsActuator* actuator, double gain);
 //---------------------------------- Assets --------------------------------------------------------
 
 // Add mesh.
+// Nullable: def
 MJAPI mjsMesh* mjs_addMesh(mjSpec* s, const mjsDefault* def);
 
 // Add height field.
@@ -1543,6 +1589,7 @@ MJAPI mjsSkin* mjs_addSkin(mjSpec* s);
 MJAPI mjsTexture* mjs_addTexture(mjSpec* s);
 
 // Add material.
+// Nullable: def
 MJAPI mjsMaterial* mjs_addMaterial(mjSpec* s, const mjsDefault* def);
 
 // Sets the vertices and normals of a mesh.
@@ -1648,6 +1695,7 @@ MJAPI mjString* mjs_getName(mjsElement* element);
 MJAPI const char* mjs_getString(const mjString* source);
 
 // Get double array contents and optionally its size.
+// Nullable: size
 MJAPI const double* mjs_getDouble(const mjDoubleVec* source, int* size);
 
 // Get plugin attributes.