examples: Add comments.

* examples/index.scm, examples/search.scm: Add comments.

2 files changed, 32 insertions, 2 deletions

diff --git a/examples/index.scm b/examples/index.scm
index 396df7c..292334e 100644
--- a/examples/index.scm
+++ b/examples/index.scm
@@ -22,25 +22,46 @@
              (xapian xapian))
 
 (define (index datapath dbpath)
+  ;; Open database for writing. call-with-writable-database
+  ;; automatically closes the database once we're done.
   (call-with-writable-database dbpath
     (lambda (db)
       (for-each
        (lambda (record)
          (match record
            ((description title identifier)
-            (let* ((idterm (string-append "Q" identifier))
+            (let* (;; Make a document and tell the term generator to
+                   ;; use it. The data of the document is stored for
+                   ;; display purposes. Storing data is optional and
+                   ;; can be skipped to cut down on database size. The
+                   ;; unique idterm ensures each document ends up in
+                   ;; the database only once no matter how many times
+                   ;; we run the database.
+                   (idterm (string-append "Q" identifier))
                    (doc (make-document #:data (call-with-output-string (cut write record <>))
                                        #:terms `((,idterm . 0))))
                    (term-generator (make-term-generator #:stem (make-stem "en")
                                                         #:document doc)))
+              ;; Index title and description with a suitable
+              ;; prefix. This is used to allow for searching separate
+              ;; fields as in title:sunwatch, description:leather,
+              ;; etc.
               (index-text! term-generator title #:prefix "S")
               (index-text! term-generator description #:prefix "XD")
+
+              ;; Index title and description without prefixes for
+              ;; general search.
               (index-text! term-generator title)
               (increase-termpos! term-generator)
               (index-text! term-generator description)
+
+              ;; Add the document to the database. The unique idterm
+              ;; ensures each object ends up in the database only once
+              ;; no matter how many times we run the indexer.
               (replace-document! db idterm doc)))))
        (call-with-input-file datapath read)))))
 
+;; Handle command line arguments
 (match (command-line)
   ((_ datapath dbpath)
    (index datapath dbpath))
diff --git a/examples/search.scm b/examples/search.scm
index 4b58313..fee945e 100644
--- a/examples/search.scm
+++ b/examples/search.scm
@@ -26,12 +26,17 @@
     ((description title identifier) title)))
 
 (define* (search dbpath querystring #:key (offset 0) (pagesize 10))
+  ;; Open database for reading. call-with-database automatically
+  ;; closes the database once we're done.
   (call-with-database dbpath
     (lambda (db)
-      (let ((query (parse-query querystring
+      (let (;; Parse querystring passing a stemmer and suitable
+            ;; prefixes for field search.
+            (query (parse-query querystring
                                 #:stemmer (make-stem "en")
                                 #:prefixes '(("title" ."S")
                                              ("description" . "XD")))))
+        ;; Fold over the results, printing them.
         (mset-fold (lambda (item _)
                      (format #t "~a: #~3,'0d ~a~%"
                              (mset-item-rank item)
@@ -41,8 +46,12 @@
                                   (document-data (mset-item-document item))
                                 read))))
                    #f
+                   ;; Get an Enquire object from the database with the
+                   ;; search results. Then, extract the MSet from the
+                   ;; Enquire object.
                    (enquire-mset (enquire db query) offset pagesize))))))
 
+;; Handle command line arguments
 (match (command-line)
   ((_ dbpath . query-terms)
    (search dbpath (string-join query-terms)))