[OSSTEST PATCH 23/60] history reporting (nfc): Documentation for the new module

[Ian Jackson <ian.jackson@xxxxxxxxxxxxx>]

Signed-off-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
---
 Osstest/HistoryReport.pm | 27 +++++++++++++++++++++++++++
 sg-report-host-history   |  6 +-----
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/Osstest/HistoryReport.pm b/Osstest/HistoryReport.pm
index cb8c6ca1..6e5ed6ec 100644
--- a/Osstest/HistoryReport.pm
+++ b/Osstest/HistoryReport.pm
@@ -51,6 +51,33 @@ our $rows_previous = 0;
 our $rows_today = 0;
 our $rows_hit = 0;
 
+
+# History report query and processing cache
+#
+# Basic principle:
+#
+# Each HTML output file corresponds to the rows of one
+# primary query.  That primary query yields rows containing
+# (at least) the columns passed to cache_set_key_cols.
+#
+# The HTML files contain caches of per-primary-row queries and
+# computations.  Each such subcomputation is identified by a
+# $cachekey, which is assigned by the calling code (but should be
+# alphanumeric).  The memoisation is keyed off the key columns and
+# $cachekey, so the subcomputation should not depend on anything else.
+#
+# The API is based on a %$jr.
+#
+# %$jr contains one entry for each for each key columns.
+#
+# It also contains one entry for each cached subcomputation.
+# The keys for these entries are "\%$cachekey".
+
+# These routines all expect the file handle ::DEBUG
+# They are not reentrant and can only be used for one HTML
+# output file in one program run.
+
+
 sub cache_set_key_cols { @key_cols = @_; }
 
 sub key ($) {
diff --git a/sg-report-host-history b/sg-report-host-history
index a195bb21..e281986d 100755
--- a/sg-report-host-history
+++ b/sg-report-host-history
@@ -204,11 +204,7 @@ END
     my $inrows = $hosts{$hostname};
     print DEBUG "FOUND ", (scalar @$inrows), " ROWS for $hostname\n";
 
-    # Each entry in @$inrows is a $jr, which is a hash
-    # It has keys for the result columns in mainquery
-    # It also has keys '%<letter>' (yes, with a literal '%')
-    # which are the results of per-job queries.
-    # The contents of $jr for each job is cached across runs.
+    # Each entry in @$inrows is a HistoryReport $jr
 
     my @rows;
     foreach my $jr (@$inrows) {
-- 
2.11.0