diff --git a/doc/includes/references.h b/doc/includes/references.h
index 31b8d118ac..1d33a1a106 100644
--- a/doc/includes/references.h
+++ b/doc/includes/references.h
@@ -3463,6 +3463,10 @@ mjsTuple* mjs_addTuple(mjSpec* s);
 mjsKey* mjs_addKey(mjSpec* s);
 mjsPlugin* mjs_addPlugin(mjSpec* s);
 mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, const mjsDefault* parent);
+// Example usage:
+// mjs_addDefault(spec, "myclass", parent);  // Named default
+// mjs_addDefault(spec, nullptr, parent);     // Only for the root unnamed default
+mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, const mjsDefault* parent);
 const char* mjs_setToMotor(mjsActuator* actuator);
 const char* mjs_setToPosition(mjsActuator* actuator, double kp, double kv[1],
                               double dampratio[1], double timeconst[1], double inheritrange);
diff --git a/include/mujoco/mujoco.h b/include/mujoco/mujoco.h
index 0ab1e8dd77..a6b1f03c0a 100644
--- a/include/mujoco/mujoco.h
+++ b/include/mujoco/mujoco.h
@@ -1566,6 +1566,10 @@ MJAPI mjsPlugin* mjs_addPlugin(mjSpec* s);
 
 // Add default.
 // Nullable: parent
+// Add a default class to the model. Pass a non-null classname for named defaults; only one unnamed default is allowed at the top level.
+// Example usage:
+// mjs_addDefault(spec, "myclass", parent);  // Named default
+// mjs_addDefault(spec, nullptr, parent);     // Only for the root unnamed default
 MJAPI mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, const mjsDefault* parent);
 
 
diff --git a/src/user/user_api.h b/src/user/user_api.h
index d400356062..bc39f25cec 100644
--- a/src/user/user_api.h
+++ b/src/user/user_api.h
@@ -157,7 +157,10 @@ MJAPI mjsKey* mjs_addKey(mjSpec* s);
 // Add plugin.
 MJAPI mjsPlugin* mjs_addPlugin(mjSpec* s);
 
-// Add default.
+// Add a default class to the model. Pass a non-null classname for named defaults; only one unnamed default is allowed at the top level.
+// Example usage:
+// mjs_addDefault(spec, "myclass", parent);  // Named default
+// mjs_addDefault(spec, nullptr, parent);     // Only for the root unnamed default
 MJAPI mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, const mjsDefault* parent);