history reporting (nfc): Documentation for the new module

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>

diff --git a/Osstest/HistoryReport.pm b/Osstest/HistoryReport.pm
index cb8c6ca12219a0031df94f802ac9b428b6eee8b7..6e5ed6ecd14e6e81a658765c3661cb68610c6a74 100644 (file)
--- 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 a195bb2127e90696340e9751f6b10deb5f645e4e..e281986da7cc20e310a353838fb6561ca3a0835e 100755 (executable)
--- 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) {