1 file changed, 29 insertions, 7 deletions

diff --git a/source/ui-stats.h b/source/ui-stats.h
index 0e61b03..718e335 100644
--- a/source/ui-stats.h
+++ b/source/ui-stats.h
@@ -1,5 +1,13 @@
-#ifndef UI_STATS_H
-#define UI_STATS_H
+/*
+ * The statistics page, which counts commits per author over a window of
+ * recent weeks, months, quarters or years and sizes the tip of the branch by
+ * language. The windows are described here rather than inside the page,
+ * because cgit.c resolves a repository's max-stats setting against the same
+ * set.
+ */
+
+#ifndef CGIT_UI_STATS_H
+#define CGIT_UI_STATS_H
 
 #include "cgit.h"
 
@@ -7,22 +15,36 @@ struct cgit_period {
 	const char code;
 	const char *name;
 	int max_periods;
+
+	// How many periods a page shows side by side.
 	int count;
 
-	/* Convert a tm value to the first day in the period */
+	// Move a tm back to the first day of the period it falls in.
 	void (*trunc)(struct tm *tm);
 
-	/* Update tm value to start of next/previous period */
+	// Step a truncated tm one whole period back or forward.
 	void (*dec)(struct tm *tm);
 	void (*inc)(struct tm *tm);
 
-	/* Pretty-print a tm value */
+	// Label the period a tm falls in. The buffer is reused, so a caller
+	// that keeps a label copies it.
 	char *(*pretty)(struct tm *tm);
 };
 
-extern int cgit_find_stats_period(const char *expr, const struct cgit_period **period);
+/*
+ * Look a period up by its one letter code or by its full name, storing the
+ * match through period when that is not NULL. The return is a one based index
+ * into the table of periods, or 0 when nothing matches, and because that
+ * table runs from the finest window to the coarsest, the index is what
+ * max-stats is compared against.
+ */
+extern int cgit_find_stats_period(const char *expr,
+				  const struct cgit_period **period);
+
+// The name of the period at a one based index, or an empty string when the
+// index names no period.
 extern const char *cgit_find_stats_periodname(int idx);
 
 extern void cgit_show_stats(void);
 
-#endif /* UI_STATS_H */
+#endif // CGIT_UI_STATS_H