1 file changed, 50 insertions, 14 deletions
diff --git a/source/ui-shared.h b/source/ui-shared.h
index b6f2797..c266951 100644
--- a/source/ui-shared.h
+++ b/source/ui-shared.h
@@ -1,9 +1,25 @@
-#ifndef UI_SHARED_H
-#define UI_SHARED_H
+/*
+ * The page furniture and the link builders every renderer shares. A page
+ * handler renders its own body and calls in here for all that surrounds it,
+ * which is the HTTP headers, the document head and footer, the header block
+ * with its tabs and search form, the error page, and an anchor to any other
+ * cgit page. Whether a site addresses a request as a path below a virtual root
+ * or as a query string is settled behind these calls, so that nothing else has
+ * to know which of the two it is looking at.
+ */
 
+#ifndef CGIT_UI_SHARED_H
+#define CGIT_UI_SHARED_H
+
+#include "cgit.h"
 extern const char *cgit_httpscheme(void);
 extern char *cgit_hosturl(void);
-extern const char *cgit_rooturl(void);
+
+/*
+ * The URL of the request being answered, which cgit_currentfullurl gives with
+ * the query string on the end as well, minus the url argument that the path
+ * was taken from.
+ */
 extern char *cgit_currenturl(void);
 extern char *cgit_currentfullurl(void);
 extern const char *cgit_loginurl(void);
@@ -13,10 +29,17 @@ extern char *cgit_fileurl(const char *reponame, const char *pagename,
 extern char *cgit_pageurl(const char *reponame, const char *pagename,
 			  const char *query);
 
+// Call fn once for every URL this repository can be cloned from.
 extern void cgit_add_clone_urls(void (*fn)(const char *));
 
+/*
+ * Each of these writes one anchor to the page and nothing around it, with name
+ * as the text a reader sees. A NULL title or class leaves that attribute out,
+ * and what follows them is the state the target page should open in.
+ */
 extern void cgit_index_link(const char *name, const char *title,
-			    const char *class, const char *pattern, const char *sort, int ofs, int always_root);
+			    const char *class, const char *pattern,
+			    const char *sort, int ofs, int always_root);
 extern void cgit_summary_link(const char *name, const char *title,
 			      const char *class, const char *head);
 extern void cgit_tag_link(const char *name, const char *title,
@@ -43,9 +66,6 @@ extern void cgit_patch_link(const char *name, const char *title,
 extern void cgit_refs_link(const char *name, const char *title,
 			   const char *class, const char *head,
 			   const char *rev, const char *path);
-extern void cgit_snapshot_link(const char *name, const char *title,
-			       const char *class, const char *head,
-			       const char *rev, const char *archivename);
 extern void cgit_diff_link(const char *name, const char *title,
 			   const char *class, const char *head,
 			   const char *new_rev, const char *old_rev,
@@ -63,26 +83,42 @@ extern void cgit_print_layout_end(void);
 
 __attribute__((format (printf,1,2)))
 extern void cgit_print_error(const char *fmt, ...);
-__attribute__((format (printf,1,0)))
-extern void cgit_vprint_error(const char *fmt, va_list ap);
 extern struct date_mode cgit_date_mode(enum date_mode_type type);
+
+/*
+ * Print the time t, which was recorded in the timezone tz, as an age. An age
+ * further back than max_relative is given as a calendar date instead, and a
+ * negative max_relative stays relative however old it is. A site that turns
+ * relative dates off gets the date either way.
+ */
 extern void cgit_print_age(time_t t, int tz, time_t max_relative);
 extern void cgit_print_http_headers(void);
 extern void cgit_redirect(const char *url, bool permanent);
 extern void cgit_print_docstart(void);
 extern void cgit_print_docend(void);
 __attribute__((format (printf,3,4)))
-extern void cgit_print_error_page(int code, const char *msg, const char *fmt, ...);
-extern void cgit_vprint_error_page(int code, const char *msg, const char *fmt, va_list ap);
+extern void cgit_print_error_page(int code, const char *msg, const char *fmt,
+				  ...);
+extern void cgit_vprint_error_page(int code, const char *msg, const char *fmt,
+				   va_list ap);
 extern void cgit_print_pageheader(void);
 extern void cgit_print_filemode(unsigned short mode);
-extern void cgit_compose_snapshot_prefix(struct strbuf *filename,
-					 const char *base, const char *ref);
 extern void cgit_print_snapshot_links(const struct cgit_repo *repo,
 				      const char *ref, const char *separator);
+
+// The name a snapshot of this repository is downloaded under, which is the
+// configured prefix or the last component of the repository URL.
 extern const char *cgit_snapshot_prefix(const struct cgit_repo *repo);
+
+/*
+ * Carry the current request into a form as hidden inputs, so that submitting
+ * it changes only what the form itself asks about. The branch and the search
+ * terms are carried only when the caller asks for them, since a form with a
+ * field of its own for either would otherwise submit that name twice.
+ */
 extern void cgit_add_hidden_formfields(int incl_head, int incl_search,
 				       const char *page);
 
+// Put path in front of the page title, its last component first.
 extern void cgit_set_title_from_path(const char *path);
-#endif /* UI_SHARED_H */
+#endif // CGIT_UI_SHARED_H