diff --git a/doc/src/guide/constraints.asciidoc b/doc/src/guide/constraints.asciidoc
index 6cc10752..4eade8ae 100644
--- a/doc/src/guide/constraints.asciidoc
+++ b/doc/src/guide/constraints.asciidoc
@@ -91,6 +91,11 @@ int(forward, Value) ->
 The value must be returned even if it is not converted
 by the constraint.
 
+The two other operations are currently experimental. They are
+meant to help implement HATEOAS type services, but proper
+support for HATEOAS is not expected to be available before
+Cowboy 3.0 because of Cowboy's current router's limitations.
+
 The `reverse` operation does the opposite: it
 takes a converted value and changes it back to what the
 user input would have been.
diff --git a/doc/src/guide/req.asciidoc b/doc/src/guide/req.asciidoc
index 754e4705..6b952284 100644
--- a/doc/src/guide/req.asciidoc
+++ b/doc/src/guide/req.asciidoc
@@ -258,7 +258,8 @@ contain two parameters of name `key`.
 
 The same is true when trying to use the PHP-style suffix `[]`.
 When a query string is `key[]=1&key[]=2`, the list returned will
-contain two parameters of name `key[]`.
+contain two parameters of name `key[]`. Cowboy does not require
+the `[]` suffix to properly handle repeated key names.
 
 When a query string is simply `key`, Cowboy will return the
 list `[{<<"key">>, true}]`, using `true` to indicate that the
@@ -291,9 +292,11 @@ If no default is provided and the value is missing, the
 query string is deemed invalid and the process will crash.
 
 When the query string is `key=1&key=2`, the value for `key`
-will be the list `[1, 2]`. Parameter names do not need to
-include the PHP-style suffix. Constraints may be used to
-ensure that only one value was passed through.
+will be the list `[<<"1">>, <<"2">>]`. Parameter names do not
+need to include the PHP-style suffix. Constraints may be used
+to ensure that only one value was given. Constraints do not
+automatically look inside the list, a custom constraint must
+be written if that is necessary.
 
 === Headers