diff --git a/docs/api.md b/docs/api.md
index 9fecb99ac..a4e2be2a0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -427,11 +427,11 @@ flag occurrences rather than `true` or `false`. Default value is thus `0`.
 
 <a name="default"></a>.default(key, value, [description])
 ---------------------------------------------------------
-.defaults(key, value, [description])
+.defaults(key, value, [description]) [DEPRECATED]
 ------------------------------------
 
-**Note:** The `.defaults()` alias is deprecated. It will be
-removed in the next major version.
+**Note:** The `.defaults()` alias is deprecated. It will be removed in the next
+major version. Use `.default()` instead.
 
 Set `argv[key]` to `value` if no option was specified in `process.argv`.