Improve documentation of mj_saveLastXML fixes #2075

PiperOrigin-RevId: 735672207
Change-Id: I951b8be9cf12a2a4965a40bb8db4de4ddda18570

doc/APIreference/functions.rst

@@ -75,9 +75,13 @@ instances will be deleted; as in :ref:`mj_compile`, the compilation error can be
 
 .. mujoco-include:: mj_saveLastXML
 
-Update XML data structures with info from low-level model, save as MJCF.
+Update XML data structures with info from low-level model created with :ref:`mj_loadXML`, save as MJCF.
 If error is not NULL, it must have size error_sz.
 
+Note that this function only saves models that have been loaded with :ref:`mj_loadXML`, the legacy loading mechanism.
+See the :ref:`model editing<meOverview>` chapter to understand the difference between the old and new model loading and
+saving mechanisms.
+
 .. _mj_freeLastXML:
 
 `mj_freeLastXML <#mj_freeLastXML>`__

doc/APIreference/functions_override.rst

@@ -47,6 +47,15 @@ struct pointers while editing the model programmatically.
 :ref:`mj_recompile` returns 0 if compilation succeed. In the case of failure, the given :ref:`mjModel` and :ref:`mjData`
 instances will be deleted; as in :ref:`mj_compile`, the compilation error can be read with :ref:`mjs_getError`.
 
+.. _mj_saveLastXML:
+
+Update XML data structures with info from low-level model created with :ref:`mj_loadXML`, save as MJCF.
+If error is not NULL, it must have size error_sz.
+
+Note that this function only saves models that have been loaded with :ref:`mj_loadXML`, the legacy loading mechanism.
+See the :ref:`model editing<meOverview>` chapter to understand the difference between the old and new model loading and
+saving mechanisms.
+
 .. _mj_saveXMLString:
 
 Save spec to XML string, return 0 on success, -1 on failure. If the length of the output buffer is too small, returns

include/mujoco/mujoco.h

@@ -110,7 +110,7 @@ MJAPI mjModel* mj_compile(mjSpec* s, const mjVFS* vfs);
 // Recompile spec to model, preserving the state, return 0 on success.
 MJAPI int mj_recompile(mjSpec* s, const mjVFS* vfs, mjModel* m, mjData* d);
 
-// Update XML data structures with info from low-level model, save as MJCF.
+// 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.
 MJAPI int mj_saveLastXML(const char* filename, const mjModel* m, char* error, int error_sz);
 

python/mujoco/introspect/functions.py

@@ -308,7 +308,7 @@ FUNCTIONS: Mapping[str, FunctionDecl] = dict([
                  type=ValueType(name='int'),
              ),
          ),
-         doc='Update XML data structures with info from low-level model, save as MJCF. If error is not NULL, it must have size error_sz.',  # pylint: disable=line-too-long
+         doc='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.',  # pylint: disable=line-too-long
      )),
     ('mj_freeLastXML',
      FunctionDecl(