From 924e2a23a6fe18e5626550e7bd588d13fc925252 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Tue, 26 Sep 2023 00:23:39 +0100
Subject: Add docstrings.

* rent.scm: Add docstrings for functions that don't have them.
---
 rent.scm | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'rent.scm')

diff --git a/rent.scm b/rent.scm
index 7730c9f..832746b 100644
--- a/rent.scm
+++ b/rent.scm
@@ -78,6 +78,7 @@
         (false-if-exception (delete-file temporary-filename))))))
 
 (define (json-ref scm . keys)
+  "Extract subtree of JSON @var{scm} that is addressed by @var{keys}."
   (match keys
     ((key other-keys ...)
      (apply json-ref
@@ -119,6 +120,8 @@
   (distance house-distance))
 
 (define (extract-variable html variable-name)
+  "Extract javascript variable of name @var{variable-name} from
+somewhere in @var{html}, a string."
   (guard (e (#t (error "Error while extracting" variable-name)))
     (let ((expression
            (match:substring
@@ -140,9 +143,12 @@
                      (substring expression (1- (string-length expression))))))))))
 
 (define (to-boolean n)
+  "Convert integer @var{n} to boolean. An integer is considered
+@code{#f} if @var{n} is 0 and @code{#t} otherwise."
   (not (zero? n)))
 
 (define (all-houses)
+  "Return a list of all houses on the OpenRent index page."
   (let ((html (bytevector->string (http-get* %openrent-index-url
                                              %openrent-index-page-cache-live-time)
                                   (native-transcoder))))
@@ -209,6 +215,7 @@
         body)))
 
 (define (uri->filename uri)
+  "Convert @var{uri} to a safe filename."
   (string-replace-substring (uri->string uri) "/" "|"))
 
 (define* (http-get* uri #:optional cache-live-time)
@@ -230,6 +237,7 @@
       get-bytevector-all)))
 
 (define (house-page-sxml house)
+  "Return the HTML of the page for @var{house} in SXML form."
   (call-with-port (open-bytevector-input-port
                    (http-get* (string-append %openrent-base-url
                                              "/" (number->string (house-property-id house)))))
@@ -249,6 +257,7 @@
       root))
 
 (define (house-title house)
+  "Find the title of @var{house}."
   (pre-post-order
    (house-page-sxml house)
    `((h1 *preorder* . ,(lambda (root . children)
@@ -259,6 +268,7 @@
      (*default* . ,handle-default))))
 
 (define (house-maximum-tenants house)
+  "Find the maximum number of tenants allowed in @var{house}."
   (pre-post-order
    (house-page-sxml house)
    `((td *preorder* . ,(lambda (root . children)
@@ -271,10 +281,13 @@
      (*default* . ,handle-default))))
 
 (define (blank-string? str)
+  "Return @code{#t} if @var{str} only contains whitespace
+characters. Else, return @code{#f}."
   (and (string? str)
        (string-every char-set:whitespace str)))
 
 (define (house-tube-stations house)
+  "Return a list of tube stations near @var{house}."
   (pre-post-order
    (house-page-sxml house)
    `((tbody . ,(lambda (root . children)
@@ -305,6 +318,9 @@
      (*default* . ,handle-default))))
 
 (define (house-cycling-distance house)
+  "Compute the cycling distance between @var{house} and work. The
+returned distance is the actual distance by cycle, and not distance as
+the crow flies."
   (call-with-port (open-bytevector-input-port
                    (http-get*
                     (string-append %osrm-base-url "/table/v1/bike/"
@@ -321,6 +337,7 @@
          1000))))
 
 (define (all-tube-lines)
+  "Return a list of all tube lines in London."
   (call-with-port (open-bytevector-input-port
                    (http-get* (string-append %tfl-base-url
                                              "/Line/Mode/tube")))
@@ -330,6 +347,7 @@
            (vector->list (json->scm port))))))
 
 (define (stations-on-line line-id)
+  "Return a list of tube stations on @var{line-id}."
   (call-with-port (open-bytevector-input-port
                    (http-get* (string-append %tfl-base-url
                                              "/Line/" line-id "/StopPoints")))
@@ -342,11 +360,13 @@
            (vector->list (json->scm port))))))
 
 (define (lines-at-station station-name)
+  "Return a list of tube lines serving @var{station-name}."
   (filter (lambda (line)
             (member station-name (stations-on-line line)))
           (all-tube-lines)))
 
 (define (list-house house)
+  "Display details of @var{house} on the current output port."
   (format (current-output-port)
           "~a (posted ~a hours ago)
 ~a/~a
@@ -371,6 +391,7 @@ Cycling distance: ~,1f km
   (newline))
 
 (define (list-houses houses)
+  "Display details of @var{houses}, a list, on the current output port."
   (format (current-output-port) "~a houses~%~%" (length houses))
   (for-each list-house houses))
 
-- 
cgit v1.2.3