extract_uri: fix, test, document

1 files changed, 25 insertions, 1 deletions

diff --git a/src/extract-uri.h b/src/extract-uri.h
index a4de3c856..ee773f458 100644
--- a/src/extract-uri.h
+++ b/src/extract-uri.h
@@ -10,7 +10,31 @@
 #ifndef SEEN_EXTRACT_URI_H
 #define SEEN_EXTRACT_URI_H
 
-char *extract_uri(char const *s, char const** endptr = nullptr);
+#include <string>
+
+/**
+ * Parse functional URI notation, as per 4.3.4 of CSS 2.1
+ *
+ * http://www.w3.org/TR/CSS21/syndata.html#uri
+ *
+ * > The format of a URI value is 'url(' followed by optional white space
+ * > followed by an optional single quote (') or double quote (") character
+ * > followed by the URI itself, followed by an optional single quote (')
+ * > or double quote (") character followed by optional white space
+ * > followed by ')'. The two quote characters must be the same.
+ *
+ * Example:
+ * \verbatim
+   url = extract_uri("url('foo')bar", &out);
+   -> url == "foo"
+   -> out == "bar"
+   \endverbatim
+ *
+ * @param s String which starts with "url("
+ * @param[out] endptr points to \c s + N, where N is the number of characters parsed
+ * @return URL string, or empty string on failure
+ */
+std::string extract_uri(char const *s, char const **endptr = nullptr);
 
 
 #endif /* !SEEN_EXTRACT_URI_H */