Add/improve some documentation comments

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

4 files changed, 34 insertions, 3 deletions

diff --git a/conkeror/linkwave.js b/conkeror/linkwave.js
index 6dc2f4b..75e3735 100644
--- a/conkeror/linkwave.js
+++ b/conkeror/linkwave.js
@@ -26,7 +26,8 @@ define_variable("linkwave_program", "linkwave",
                 "The location of the linkwave executable.");
 
 function linkwave_add_url(I, url, title)
-{
+{   // Add URL to linkwave, ask for a title (provide TITLE as a
+    // default), description and any number of tags.
     let url_string = load_spec_uri_string(load_spec(url));
     let title = yield I.minibuffer.read($prompt="name (required): ",
                                         $initial_value=title);
@@ -55,7 +56,7 @@ function linkwave_add(I) {
         I.window.minibuffer.message('Couldn\'t add to linkwave');
 }
 interactive("linkwave-add",
-            "Bookmark a page in linkwave",
+            "Bookmark the current page in linkwave",
             linkwave_add);
 
 function linkwave_add_link(I) {
@@ -70,7 +71,7 @@ function linkwave_add_link(I) {
         I.window.minibuffer.message('Couldn\'t add to linkwave');
 }
 interactive("linkwave-add-link",
-            "Bookmark a link in linkwave",
+            "Select and bookmark a link in linkwave",
             linkwave_add_link);
 
 provide("linkwave");
diff --git a/src/convert.scm b/src/convert.scm
index 3229823..99f42b7 100644
--- a/src/convert.scm
+++ b/src/convert.scm
@@ -28,11 +28,18 @@
 (require-library srfi-4)
 
 (define (blob->seconds blob)
+  ;; Convert BLOB to an integer representing the seconds since
+  ;; 01-01-1970 (standard unix timstamp).  This has to be done because
+  ;; in the previous version of linkwave I stored the timestamp as a
+  ;; blob and CHICKEN doesn't seem to like blobs much.
   (if (u32vector? blob)
       (u32vector-ref (blob->u32vector blob) 0)
       0))
 
 (define (convert-table db name converter #!optional select)
+  ;; Convert NAME from DB using CONVERTER for each specific row.  The
+  ;; optional SELECT should be an SQL query that will be used to fetch
+  ;; the rows to convert.
   (let ((count (first-result db (string-append "SELECT COUNT(*) FROM " name)))
         (progress 0))
     (for-each-row (lambda args
@@ -43,6 +50,8 @@
     (newline)))
 
 (define (convert)
+  ;; Convert an old database into a new one and then replace the old
+  ;; with the new.
   (let ((old-db (open-database (data-file "linkwave.db")))
         (new-db (open-database (data-file "nlinkwave.db"))))
     (execute new-db "CREATE TABLE bookmark (url VARCHAR(255) UNIQUE, date INTEGER, name VARCHAR(255), description TEXT)")
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")
diff --git a/src/paths.scm b/src/paths.scm
index af2fe2e..5f4f2d2 100644
--- a/src/paths.scm
+++ b/src/paths.scm
@@ -23,6 +23,9 @@
 (declare (unit paths))
 
 (define (stored-file xdg-env file)
+  ;; Get FILE either from `XDG-ENV/linkwave/' or from
+  ;; `$HOME/.linkwave/'.  Prefer any existing file over any other, but
+  ;; prefer files using XDG-ENV over `$HOME'.
   (let ((xdg (get-environment-variable xdg-env))
         (stored-file (string-append (get-environment-variable "HOME") "/.linkwave/" file)))
     (unless (or (file-exists? stored-file) (not xdg))
@@ -31,8 +34,13 @@
 
 (: config-file (string -> string))
 (define (config-file file)
+  ;; Use `stored-file' to get configuration file FILE.  Configuration
+  ;; files are stored under `$XDG_CONFIG_HOME' if the XDG standard is
+  ;; used.
   (stored-file "XDG_CONFIG_HOME" file))
 
 (: data-file (string -> string))
 (define (data-file file)
+  ;; Use `stored-file' to get data file FILE. Data files are stored
+  ;; under `$XDG_DATA_HOME' if the XDG standard is used.
   (stored-file "XDG_DATA_HOME" file))