Merge branch 'doc' into jcal

23 files changed, 152 insertions, 14 deletions

diff --git a/tests/base64.scm b/tests/base64.scm
index b0bb992a..59a8784c 100644
--- a/tests/base64.scm
+++ b/tests/base64.scm
@@ -1,6 +1,10 @@
+;;; Commentary:
+;; Test that Base64 encoding and decoding works
+;; Examples from RFC4648
+;;; Code:
+
 (((base64) base64encode base64decode))
 
-;; Examples from RFC4648
 
 (test-equal "" (base64encode ""))
 (test-equal "Zg==" (base64encode "f"))
diff --git a/tests/cpp.scm b/tests/cpp.scm
index d83ba554..84bd4b92 100644
--- a/tests/cpp.scm
+++ b/tests/cpp.scm
@@ -1,3 +1,7 @@
+;;; Commentary:
+;; Tests my parser for a subset of the C programming language.
+;;; Code:
+
 (((c lex) lex)
  ((c parse) parse-lexeme-tree))
 
diff --git a/tests/datetime-compare.scm b/tests/datetime-compare.scm
index 649dc59f..f2585f46 100644
--- a/tests/datetime-compare.scm
+++ b/tests/datetime-compare.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Tests that all ordering predicates for dates, 
+;; times, and datetimes hold.
+;;; Code:
+
 (((datetime)
   date
   datetime time
diff --git a/tests/datetime-util.scm b/tests/datetime-util.scm
index 123229c7..28317676 100644
--- a/tests/datetime-util.scm
+++ b/tests/datetime-util.scm
@@ -1,3 +1,9 @@
+;;; Commentary:
+;; Tests timespan overlaps and month-streams.
+;; Separate from tests/datetime.scm since 
+;; (datetime util) originally was its own module.
+;;; Code:
+
 (((datetime) date time datetime
   month-stream in-date-range? timespan-overlaps?)
  ((srfi srfi-41) stream->list stream-take
diff --git a/tests/datetime.scm b/tests/datetime.scm
index 83750472..5bf2df6d 100644
--- a/tests/datetime.scm
+++ b/tests/datetime.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Tests date, time, and datetime creation, 
+;; (output) formatting, and arithmetic.
+;;; Code:
+
 (((datetime) date+ date-
   time+ time-
   year month day
diff --git a/tests/display b/tests/display
new file mode 100755
index 00000000..e58288a2
--- /dev/null
+++ b/tests/display
@@ -0,0 +1,2 @@
+#!/bin/bash
+guild display-commentary *.scm | sed -e 's/^ /    /' -e 's/^\S/\n&/g'
diff --git a/tests/let.scm b/tests/let.scm
index 82919b49..81a34131 100644
--- a/tests/let.scm
+++ b/tests/let.scm
@@ -1,3 +1,7 @@
+;;; Commentary:
+;; Tests my custom let*.
+;;; Code:
+
 (((calp util) let*)
  ((guile) set!))
 
diff --git a/tests/param.scm b/tests/param.scm
index 0c4190dd..23704948 100644
--- a/tests/param.scm
+++ b/tests/param.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Checks that parameters (1) are correctly parsed and stored.
+;; (1): 'A', and 'B' in the line "KEY;A=1;B=2:Some text"
+;;; Code:
+
 (((vcomponent base) param prop* parameters)
  ((vcomponent parse) parse-calendar)
  ((calp util) sort*))
diff --git a/tests/recurrence-id.scm b/tests/recurrence-id.scm
index 601b0f71..be58d924 100644
--- a/tests/recurrence-id.scm
+++ b/tests/recurrence-id.scm
@@ -1,3 +1,9 @@
+;;; Commentary:
+;; Tests that exceptions (in the recurrence-id meaning) 
+;; in recurrence sets are handled correctly.
+;; TODO Is however far from done.
+;;; Code:
+
 (((srfi srfi-41) stream->list)
  ((vcomponent) parse-calendar)
  ((vcomponent recurrence) generate-recurrence-set)
@@ -6,6 +12,23 @@
 
 (define uid (symbol->string (gensym "areallyuniqueid")))
 
+;; TODO standardize vcomponents for tests as xcal, for example:
+`(vcalendar
+   (children
+     (vevent
+       (properties
+         (summary (text "Changing type on Recurrence-id."))
+         (uid (text ,uid))
+         (dtstart (date "20090127"))))
+     (vevent
+       (properties
+         (summary (text "Changing type on Recurrence-id."))
+         (uid (text ,uid))
+         (dtstart (params (TZID "Europe/Stockholm")) 
+                  (date-time "20100127T120000"))
+         (recurrence-id (date "20100127"))
+         (summary "This instance only has a time component")))))
+
 (define ev
  (call-with-input-string
      (format #f "BEGIN:VCALENDAR
diff --git a/tests/recurrence.scm b/tests/recurrence.scm
index 6ced6af0..ceab07cd 100644
--- a/tests/recurrence.scm
+++ b/tests/recurrence.scm
@@ -1,9 +1,17 @@
 ;;; Commentary:
+;; Advanced tests of "generate-recurrence-set", along with 
+;; format-recurrence-rule which checks that human readable
+;; representations of the RRULES work.
+;;
+;; Also contains the tests for EXDATE.
+;;
+;; Examples copied from RFC5545
+;;; Code:
+
 ;; The human readable tests are expected to fail with any change to the
 ;; text creator. Proof-read them manually, and update the test cases
 ;; to match. `x-summary' used for target string. Target strings should
 ;; be in swedish.
-;;; Code:
 
 (((vcomponent recurrence parse) parse-recurrence-rule)
  ((vcomponent recurrence generate) generate-recurrence-set)
@@ -16,8 +24,6 @@
  ((srfi srfi-41) stream->list)
  ((srfi srfi-88) keyword->string))
 
-;; Examples copied from RFC5545
-
 (define (run-test comp)
 
   (test-equal (string-append "RSET: " (prop comp 'SUMMARY))
diff --git a/tests/recurring.scm b/tests/recurring.scm
index a3f98027..d677971e 100644
--- a/tests/recurring.scm
+++ b/tests/recurring.scm
@@ -1,3 +1,7 @@
+;;; Commentary:
+;; General tests of "generate-recurrence-set".
+;;; Code:
+
 (((srfi srfi-41) stream-take stream-map stream->list stream-car)
  ((datetime) day-stream)
  ((vcomponent base) extract prop)
diff --git a/tests/rrule-parse.scm b/tests/rrule-parse.scm
index b7a851a0..e2990cbc 100644
--- a/tests/rrule-parse.scm
+++ b/tests/rrule-parse.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Basic tests that recurrence rule parsing works.
+;; Including that it fails on invalid output.
+;;; Code:
+
 (((vcomponent recurrence parse)
   parse-recurrence-rule)
  ((vcomponent recurrence) make-recur-rule)
diff --git a/tests/run-tests.scm b/tests/run-tests.scm
index 670a1784..4060a170 100755
--- a/tests/run-tests.scm
+++ b/tests/run-tests.scm
@@ -2,6 +2,13 @@
 -s
 !#
 
+;;; Commentary:
+;; Not a test, but a script that runs tests.
+;; Assumes that all other .scm files in this directory are test files,
+;; and should thereby follow the test-file syntax.
+;; TODO document the testfile syntax.
+;;; Code:
+
 (eval-when (compile load)
  (define here (dirname (current-filename))))
 
diff --git a/tests/server.scm b/tests/server.scm
index a9cb870e..706697f6 100644
--- a/tests/server.scm
+++ b/tests/server.scm
@@ -1,6 +1,21 @@
-(((web http make-routes) parse-endpoint-string))
+;;; Commentary:
+;; Tests parse-endpoint-string, used for defining server routes.
+;;; Code:
 
-(test-assert (parse-endpoint-string "/static/:dir/:file"))
-;; => "/static/([^/]+)/([^/]+)"
-;; => (dir file)
+(((web http make-routes) parse-endpoint-string)
+ ((calp util) let*))
 
+(test-assert "Check that parsing doesn't crash"
+  (parse-endpoint-string "/static/:dir/:file"))
+
+;; Checks that parsing produces correct results
+(let* ((path args (parse-endpoint-string "/static/:dir/:file")))
+  (test-equal "/static/([^/]+)/([^/]+)" path)
+  (test-equal '(dir file) args))
+
+
+;; Checks that parsing with custom regex works
+;; along with literal periods.
+(let* ((path args (parse-endpoint-string "/static/:filename{.*}.:ext")))
+  (test-equal "/static/(.*)\\.([^/.]+)" path)
+  (test-equal '(filename ext) args))
diff --git a/tests/srfi-41-util.scm b/tests/srfi-41-util.scm
index 61bce71e..3c2c3f0f 100644
--- a/tests/srfi-41-util.scm
+++ b/tests/srfi-41-util.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Tests (srfi srfi-41 util).
+;; Currently only tests stream-paginate.
+;;; Code:
+
 (((srfi srfi-41 util) stream-paginate)
  ((srfi srfi-41) stream->list stream-ref stream-from
   stream-filter stream-car stream)
diff --git a/tests/termios.scm b/tests/termios.scm
index 214a12a0..c0cb4323 100755..100644
--- a/tests/termios.scm
+++ b/tests/termios.scm
@@ -1,10 +1,8 @@
 ;;; Commentary:
-
 ;; Tests that my termios function works, at least somewhat.
-;; Note that this actually modifies the terminal it's run on, and might fail if
-;; the terminal doesn't support the wanted modes. See termios(3).
+;; Note that this actually modifies the terminal it's run on, and might fail 
+;; if the terminal doesn't support the wanted modes. See termios(3).
 ;; It might also leave the terminal in a broken state if exited prematurely.
-
 ;;; Code:
 
 (((calp util) set!)
diff --git a/tests/tz.scm b/tests/tz.scm
index 8ccd636d..147f0807 100644
--- a/tests/tz.scm
+++ b/tests/tz.scm
@@ -1,3 +1,11 @@
+;;; Commentary:
+;; Tests that datetime->unix-time correctly converts between Olssen
+;; timezone definitions (e.g. Europe/Stockholm), into correct times
+;; and offsets (in unix time).
+;; Also indirectly tests the Zone Info Compiler (datetime zic), since
+;; the zoneinfo comes from there.
+;;; Code:
+
 (((datetime)
   parse-ics-datetime
   datetime date time
diff --git a/tests/util.scm b/tests/util.scm
index f917b5ce..ed5abfd1 100644
--- a/tests/util.scm
+++ b/tests/util.scm
@@ -1,3 +1,7 @@
+;;; Commentary:
+;; Checks some prodecuders from (calp util)
+;;; Code:
+
 (((calp util) filter-sorted set/r!))
 
 (test-equal "Filter sorted"
diff --git a/tests/vcomponent-control.scm b/tests/vcomponent-control.scm
index 8cc87a0a..2ee4c243 100644
--- a/tests/vcomponent-control.scm
+++ b/tests/vcomponent-control.scm
@@ -1,3 +1,7 @@
+;;; Commentary:
+;; Tests that with-replaced-properties work.
+;;; Code:
+
 (((vcomponent control) with-replaced-properties)
  ((vcomponent) parse-calendar)
  ((vcomponent base) prop))
diff --git a/tests/vcomponent-datetime.scm b/tests/vcomponent-datetime.scm
index f7bb00f4..0bc584f6 100644
--- a/tests/vcomponent-datetime.scm
+++ b/tests/vcomponent-datetime.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Tests that event-clamping (checking how long part of an event
+;; overlaps another time span) works.
+;;; Code:
+
 (((datetime)
   date time
   datetime)
@@ -13,10 +18,15 @@ DTEND:20200401T100000
 END:VEVENT"
                parse-calendar))
 
+;; |-----------------| test interval
+;;                 |----------| event interval
 
 (test-equal "Correct clamping"
-  (datetime time: (time hour: 7))
-  (event-length/clamped #2020-03-23 #2020-03-29 ev))
+  (datetime time: (time hour: 7)) ; 2020-03-29T17:00 - 2020-03-30T00:00
+  (event-length/clamped 
+    #2020-03-23 ; a time way before the start of the event
+    #2020-03-29 ; a time slightly after the end of the event
+    ev))
 
 (define utc-ev (call-with-input-string
                "BEGIN:VEVENT
diff --git a/tests/vcomponent.scm b/tests/vcomponent.scm
index 0d81ab0e..15c83845 100644
--- a/tests/vcomponent.scm
+++ b/tests/vcomponent.scm
@@ -1,3 +1,7 @@
+;;; Commentary:
+;; Test that vcomponent parsing works at all.
+;;; Code:
+
 (((vcomponent base) prop)
  ((vcomponent) parse-calendar))
 
diff --git a/tests/web-server.scm b/tests/web-server.scm
index 6b315319..bce05d0e 100644
--- a/tests/web-server.scm
+++ b/tests/web-server.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Checks that HTTP server can start correctly, and that at least some
+;; endpoints return correct information.
+;;; Code:
+
 (((calp server routes) make-make-routes)
  ((web server) run-server)
  ((ice-9 threads) call-with-new-thread cancel-thread)
diff --git a/tests/xcal.scm b/tests/xcal.scm
index 1748cba3..babb2218 100644
--- a/tests/xcal.scm
+++ b/tests/xcal.scm
@@ -1,3 +1,8 @@
+;;; Commentary:
+;; Basic tests of xcal convertion.
+;; Currently only checks that events survive a round trip.
+;;; Code:
+
 (((vcomponent xcal parse) sxcal->vcomponent)
  ((vcomponent xcal output) vcomponent->sxcal)
  ((vcomponent ical parse) parse-calendar)