Add/improve some documentation comments

Since CHICKEN scheme doesn't do docstrings I'm just using comments.

1 files changed, 13 insertions, 0 deletions

diff --git a/src/linkwave.scm b/src/linkwave.scm
index 0783485..fbb25fd 100644
--- a/src/linkwave.scm
+++ b/src/linkwave.scm
@@ -28,6 +28,8 @@
 
 (: string-no-null (string -> string))
 (define (string-no-null str)
+  ;; If STR contains a \0 byte at the end, remove it, otherwise return
+  ;; STR unchanged.
   (if (and (> (string-length str) 0)
            (char=? (string-ref str (- (string-length str) 1)) #\nul))
       (substring str 0 (- (string-length str) 1))
@@ -35,14 +37,21 @@
 
 (: print-row (string fixnum string string -> void))
 (define (print-row url seconds name description)
+  ;; Print URL, SECONDS, NAME and DESCRIPTION to the standard output
+  ;; stream.
   (format #t "~a~%  ~a~%  ~a~%  ~a~%~%" (string-no-null name) (string-no-null description)
           (string-no-null url) (seconds->string seconds)))
 
 (define (add-tag db name)
+  ;; Add NAME to the `tag' table in DB.
   (execute db "INSERT INTO tag VALUES (?)" name)
   (last-insert-rowid db))
 
 (define (add-bookmark db url name description tags)
+  ;; Add a bookmark to the `bookmark' table in DB.  URL is the url of
+  ;; the bookmark, NAME the title, DESCRIPTION a (possibly longer)
+  ;; description of the bookmark and TAGS is a list of tags to assign
+  ;; to it.  Each tag will be created if necessary.
   (execute db "INSERT INTO bookmark VALUES (?, STRFTIME('%s'), ?, ?)"
            url name description)
   (let ((bookmark-id (last-insert-rowid db)))
@@ -59,11 +68,15 @@
               tags)))
 
 (define (url-string? str)
+  ;; Is STR a URL?  Very naïve, assumes all URLs begin with either
+  ;; `http://' or `https://', should be improved.
   (and (> (string-length str) 7)
        (or (string= (substring str 0 7) "http://")
            (string= (substring str 0 8) "https://"))))
 
 (define (main args)
+  ;; Open a database connection, do what the user asked and close it
+  ;; again.
   (let ((db (open-database (data-file "linkwave.db"))))
     (if (null? args)
         (for-each-row print-row db "select * from bookmark")