diff --git a/docs/simplesamlphp-reference-idp-hosted.txt b/docs/simplesamlphp-reference-idp-hosted.txt
index 9d76115cd21dffaaa1eb28aae26555df5e65b524..cea6fe1f14fc79c3cff122d222158d79402f40ae 100644
--- a/docs/simplesamlphp-reference-idp-hosted.txt
+++ b/docs/simplesamlphp-reference-idp-hosted.txt
@@ -183,6 +183,31 @@ The following SAML 2.0 options are available:
 
 :   Note that this option can be set for each SP in the [SP-remote metadata](./simplesamlphp-reference-sp-remote).
 
+`NameIDFormat`
+:   The format of the NameID supported by this IdP. Defaults to the `transient` format if unspecified.
+    This parameter can be configured in multiple places, and the actual value used is fetched from metadata with
+    the following priority:
+
+:   1.  SP Remote Metadata
+
+    2.  IdP Hosted Metadata
+
+:   The three most commonly used values are:
+
+:   1.  `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
+    2.  `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
+    3.  `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
+
+:   The `transient` format will generate a new unique ID every time
+    the user logs in.
+
+:   To properly support the `persistent` and `emailAddress` formats,
+    you should configure [NameID generation filters](./saml:nameid)
+    on your IdP.
+
+:   Note that the value set here will be added to the metadata generated for this IdP,
+    in the `NameIDFormat` element.
+
 `saml20.sendartifact`
 :   Set to `TRUE` to enable the IdP to send responses with the HTTP-Artifact binding.
     Defaults to `FALSE`.
diff --git a/modules/saml/docs/sp.txt b/modules/saml/docs/sp.txt
index 4cc32330d942bd6b7ca76b8bbe2b43d8c03f6530..5d6c86217193d0d5bcdbae422976a5700cd3c6b0 100644
--- a/modules/saml/docs/sp.txt
+++ b/modules/saml/docs/sp.txt
@@ -297,7 +297,9 @@ Options
 
 `NameIDPolicy`
 :   The format of the NameID we request from the IdP.
-    Defaults to the transient format if unspecified.
+    Defaults to the `transient` format if unspecified.
+
+:   If this option is set, its value will be added to the metadata generated for this SP, in the NameIDFormat element.
 
 :   *Note 1*: This option replaces the `NameIDFormat` option found in `saml20-sp-hosted`.