Restyle the sources and fix the audit's findings

1 file changed, 50 insertions, 20 deletions

diff --git a/source/html.h b/source/html.h
index 0818ab5..ecc7141 100644
--- a/source/html.h
+++ b/source/html.h
@@ -1,53 +1,83 @@
-#ifndef HTML_H
-#define HTML_H
+/*
+ * The printing side of cgit, which every page is written through. Text is
+ * handed in as plain strings and the call a renderer picks decides how it is
+ * escaped for where it lands, whether that is page text, an attribute value, a
+ * URL path, a query argument or a quoted HTTP header. Output is buffered
+ * rather than written as it is produced, so the flush and capture calls below
+ * are part of the contract for anything that reaches stdout by another route.
+ */
+
+#ifndef CGIT_HTML_H
+#define CGIT_HTML_H
 
 #include "cgit.h"
 
+// How much of a generated run to build before handing it to html_raw. Growing
+// past this gains nothing, since html_raw gathers what it is given into a
+// buffer of its own, and a run built whole would instead be sized by the file
+// it came from, which the blob limits do not bound.
+#define HTML_BATCH (64 * 1024)
+
 extern void html_raw(const char *txt, size_t size);
 extern void html(const char *txt);
 
-/* How much of a generated run to build before handing it to html_raw. Batching
- * is what removes the write per line, and html_raw already gathers what it is
- * given into one buffer, so nothing is gained by growing past this. A run built
- * whole would instead be sized by the file it was generated from, which the
- * blob limits do not bound. */
-#define HTML_BATCH (64 * 1024)
-
-/* Write out whatever page output is still buffered. Call before anything
- * other than html_raw writes to stdout. */
+/*
+ * Write out whatever page output is still buffered. Call this before anything
+ * other than html_raw writes to stdout.
+ */
 extern void html_flush(void);
 
-/* Collect page output into sb rather than writing it, until html_capture_end.
- * Must not span a filter or anything else that writes to stdout directly. */
+/*
+ * Collect page output into sb rather than writing it, until html_capture_end.
+ * A capture must not span a filter or anything else that writes to stdout
+ * directly, since that output would escape the capture.
+ */
 extern void html_capture_begin(struct strbuf *sb);
 extern void html_capture_end(void);
 
 __attribute__((format (printf,1,2)))
-extern void htmlf(const char *format,...);
+extern void htmlf(const char *format, ...);
 
 __attribute__((format (printf,1,2)))
-extern void html_txtf(const char *format,...);
+extern void html_txtf(const char *format, ...);
 
 __attribute__((format (printf,1,0)))
 extern void html_vtxtf(const char *format, va_list ap);
 
 __attribute__((format (printf,1,2)))
-extern void html_attrf(const char *format,...);
+extern void html_attrf(const char *format, ...);
 
 extern void html_txt(const char *txt);
+
+/*
+ * Escape at most len bytes of txt. The return is what is left of that budget,
+ * and a caller prints an ellipsis when it comes back negative.
+ */
 extern ssize_t html_ntxt(const char *txt, size_t len);
+
 extern void html_attr(const char *txt);
 extern void html_url_path(const char *txt);
 extern void html_url_arg(const char *txt);
 extern void html_header_arg_in_quotes(const char *txt);
 extern void html_hidden(const char *name, const char *value);
-extern void html_option(const char *value, const char *text, const char *selected_value);
+
+__attribute__((format (printf,1,2)))
+extern char *cgit_fmt(const char *format, ...);
+
+__attribute__((format (printf,1,2)))
+extern char *cgit_fmtalloc(const char *format, ...);
+
+extern void html_option(const char *value, const char *text,
+			const char *selected_value);
 extern void html_intoption(int value, const char *text, int selected_value);
-extern void html_link_open(const char *url, const char *title, const char *class);
+extern void html_link_open(const char *url, const char *title,
+			   const char *class);
 extern void html_link_close(void);
 extern void html_fileperm(unsigned short mode);
 extern int html_include(const char *filename);
 
-extern void http_parse_querystring(const char *txt, void (*fn)(const char *name, const char *value));
+extern void http_parse_querystring(const char *txt,
+				   void (*fn)(const char *name,
+					      const char *value));
 
-#endif /* HTML_H */
+#endif // CGIT_HTML_H