From f40fcaf64f3d545fac06c7a39f8aa0df1181393e Mon Sep 17 00:00:00 2001
From: sternenseemann <0rpkxez4ksa01gb3typccl0i@systemli.org>
Date: Tue, 25 Aug 2020 13:03:49 +0200
Subject: doc(cgiutil): document server_url

---
 TODO      |  2 +-
 cgiutil.h | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/TODO b/TODO
index 216db20..9c206f5 100644
--- a/TODO
+++ b/TODO
@@ -6,4 +6,4 @@ tests for xml.c | id:b9e91d022be6bdc70e7ab082743826370b713c72
 improve man3 situation | id:bf918930f6361c30f288c42894cbf9b0541c3340
 use errno instead of returning HTTP status codes in make_index | id:bfa35c48dcedbecd3a951eba243c4840178289ed
 sandboxing, at least chroot | id:f209aec893fe310c8276f64f6ff4a3208a2a4f28
-document cgiutil, timeutil and stringutil | id:fd05b97115848a8b22231a477b8252373bd87264
+document timeutil and stringutil | id:fd05b97115848a8b22231a477b8252373bd87264
diff --git a/cgiutil.h b/cgiutil.h
index b90b895..f809b25 100644
--- a/cgiutil.h
+++ b/cgiutil.h
@@ -92,4 +92,20 @@ int http_errno(int err);
  */
 int urlencode_realloc(char **input, int size);
 
+/*!
+ * @brief Returns URL of server addressed by the current CGI request
+ *
+ * server_url() uses the CGI 1.1 environment variables `SERVER_NAME`
+ * and `SERVER_PORT` to construct an URL to the server the current
+ * request is addressed to. Since CGI only reveals the HTTP version
+ * used and not wether an encrypted version of HTTP is used,
+ * server_url() will use the parameter `https` to decide which protocol
+ * identifier to prefix.
+ *
+ * The returned `char *` is dynamically allocated and must be cleaned
+ * up using `free()` before it goes out of scope.
+ *
+ * @param https if true, prefix `https://` else `http://`
+ * @return Pointer to dynamically allocated char buffer containing the URL.
+ */
 char *server_url(bool https);
-- 
cgit 1.4.1