diff --git a/README.md b/README.md
index 9ac79a915..3cd30dd84 100644
--- a/README.md
+++ b/README.md
@@ -115,7 +115,7 @@ components (path, host, and so forth).
 
 ### Parsing & Validation
 
-- Parse and validate a URL from an ASCII or UTF-8 string
+- Parse and validate a URL from an ASCII or a valid UTF-8 string.
 
 ```cpp
 ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
@@ -144,7 +144,8 @@ if(url) {
 ```
 
 For simplicity, in the examples below, we skip the check because
-we know that parsing succeeds.
+we know that parsing succeeds. All strings are assumed to be valid
+UTF-8 strings.
 
 ### Examples
 
diff --git a/include/ada/parser.h b/include/ada/parser.h
index 4f815621d..c539867e3 100644
--- a/include/ada/parser.h
+++ b/include/ada/parser.h
@@ -27,7 +27,10 @@ struct url;
 namespace ada::parser {
 
 /**
- * Parses a url.
+ * Parses a url. The parameter user_input is the input to be parsed:
+ * it should be a valid UTF-8 string. The parameter base_url is an optional
+ * parameter that can be used to resolve relative URLs. If the base_url is
+ * provided, the user_input is resolved against the base_url.
  */
 template <typename result_type = ada::url_aggregator>
 result_type parse_url(std::string_view user_input,