From e3d4594eb7a2f9db7fc31ec0cc5ae119be3fa55a Mon Sep 17 00:00:00 2001 From: Tom Willemsen Date: Fri, 28 Dec 2012 22:03:55 +0100 Subject: [PATCH] Add/improve some documentation comments Since CHICKEN scheme doesn't do docstrings I'm just using comments. --- conkeror/linkwave.js | 7 ++++--- src/convert.scm | 9 +++++++++ src/linkwave.scm | 13 +++++++++++++ src/paths.scm | 8 ++++++++ 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))