Documentation and disambiguation

Separate package name hierarchies for clj and cljs parts of the system, so that it's unambiguous what package (e.g. 'youyesyet.core' is.

env/dev/cljs/youyesyet/dev.cljs

@@ -1,5 +1,5 @@
-(ns ^:figwheel-no-load youyesyet.app
-  (:require [youyesyet.core :as core]
+(ns ^:figwheel-no-load youyesyet.canvasser-app.app
+  (:require [youyesyet.canvasser-app.core :as core]
             [devtools.core :as devtools]
             [figwheel.client :as figwheel :include-macros true]))
 

env/prod/cljs/youyesyet/prod.cljs

@@ -1,5 +1,5 @@
 (ns youyesyet.app
-  (:require [youyesyet.core :as core]))
+  (:require [youyesyet.canvasser-app.core :as core]))
 
 ;;ignore println statements in prod
 (set! *print-fn* (fn [& _]))

project.clj

@@ -121,7 +121,7 @@
                    {:app
                     {:source-paths ["src/cljs" "src/cljc" "env/dev/cljs"]
                      :compiler
-                     {:main "youyesyet.app"
+                     {:main "youyesyet.canvasser-app.app"
                       :asset-path "/js/out"
                       :output-to "target/cljsbuild/public/js/app.js"
                       :output-dir "target/cljsbuild/public/js/out"

resources/sql/queries.sql

@@ -31,6 +31,7 @@
 INSERT INTO addresses
 (address, postcode, district_id, latitude, longitude)
 VALUES (:address, :postcode, :district, :latitude, :longitude)
+RETURNING id
 
 -- :name update-address! :! :n
 -- :doc update an existing address record
@@ -54,6 +55,7 @@ WHERE id = :id
 INSERT INTO authorities
 (id)
 VALUES (:id)
+RETURNING id
 
 -- :name update-authority! :! :n
 -- :doc update an existing authority record
@@ -81,6 +83,7 @@ WHERE id = :id
 INSERT INTO canvassers
 (username, fullname, elector_id, address_id, phone, email, authority_id, authorised)
 VALUES (:username, :fullname, :elector_id, :address_id, :phone, :email, :authority_id, :authorised)
+RETURNING id
 
 -- :name update-canvasser! :! :n
 -- :doc update an existing canvasser record
@@ -114,6 +117,7 @@ WHERE id = :id
 INSERT INTO districts
 (id, name)
 VALUES (:id, :name)
+RETURNING id
 
 -- :name update-district! :! :n
 -- :doc update an existing district record
@@ -137,6 +141,7 @@ WHERE id = :id
 INSERT INTO electors
 (name, address_id, phone, email)
 VALUES (:name, :address_id, :phone, :email)
+RETURNING id
 
 -- :name update-elector! :! :n
 -- :doc update an existing elector record
@@ -160,6 +165,7 @@ WHERE id = :id
 INSERT INTO followupactions
 (request_id, actor, date, notes, closed)
 VALUES (:request_id, :actor, :date, :notes, :closed)
+RETURNING id
 
 -- We don't update followup actions. They're permanent record.
 
@@ -179,6 +185,7 @@ WHERE id = :id
 INSERT INTO followuprequests
 (elector_id, visit_id, issue_id, method_id)
 VALUES (:elector_id, :visit_id, :issue_id, :method_id)
+RETURNING id
 
 -- We don't update followup requests. They're permanent record.
 
@@ -195,6 +202,7 @@ WHERE id = :id
 INSERT INTO issueexpertise
 (canvasser_id, issue_id, method_id)
 VALUES (:canvasser_id, :issue_id, :method_id)
+-- issueexertise is a link table, doesn't have an id field.
 
 -- :name update-issueexpertise! :! :n
 -- :doc update an existing issueexpertise record
@@ -219,6 +227,8 @@ WHERE id = :id
 INSERT INTO issues
 (id, url, content, current)
 VALUES (:id, :url, :content, :current)
+RETURNING id
+
 
 -- :name update-issue! :! :n
 -- :doc update an existing issue record
@@ -244,6 +254,7 @@ WHERE id = :id
 INSERT INTO visits
 (address_id, canvasser_id)
 VALUES (:address_id, :canvasser_id)
+RETURNING id
 
 -- visits is audit data; we don't update it.
 
@@ -277,6 +288,13 @@ select * from canvassers_by_team
 select * from canvassers_by_introducer
   where introducer = :introducer_id
 
+-- :name get-canvassers-by-search :? :*
+-- :doc Get details of all authorised canvassers whose details match this search string.
+select * from canvassers
+  where name like '%' || :search || '%'
+     or username like '%' || :search || '%'
+     or email like '%' || :search || '%'
+
 -- :name get-teams_by_organiser :? :*
 -- :doc Get details of all the teams organised by the canvasser with the specified id
 select * from teams_by_organiser

src/clj/youyesyet/config.clj

@@ -1,4 +1,6 @@
-(ns youyesyet.config
+(ns ^{:doc "Read configuration."
+      :author "Simon Brooke"}
+  youyesyet.config
   (:require [cprop.core :refer [load-config]]
             [cprop.source :as source]
             [mount.core :refer [args defstate]]))

src/clj/youyesyet/db/core.clj

@@ -1,4 +1,6 @@
-(ns youyesyet.db.core
+(ns ^{:doc "Database access functions."
+      :author "Simon Brooke"}
+  youyesyet.db.core
   (:require
     [cheshire.core :refer [generate-string parse-string]]
     [clojure.java.jdbc :as jdbc]

src/clj/youyesyet/db/schema.clj

@@ -1,4 +1,5 @@
-(ns youyesyet.db.schema
+(ns ^{:doc "Korma-flavour database setup, now obsolete but retained for documentation."
+      :author "Simon Brooke"} youyesyet.db.schema
   (:require [clojure.java.jdbc :as sql]
             [korma.core :as kc]
             [youyesyet.db.core :as yyydb]))

src/clj/youyesyet/handler.clj

@@ -1,4 +1,6 @@
-(ns youyesyet.handler
+(ns ^{:doc "Handlers for starting and stopping the webapp."
+      :author "Simon Brooke"}
+  youyesyet.handler
   (:require [compojure.core :refer [routes wrap-routes]]
             [youyesyet.layout :refer [error-page]]
             [youyesyet.routes.authenticated :refer [authenticated-routes]]

src/clj/youyesyet/layout.clj

@@ -1,4 +1,6 @@
-(ns youyesyet.layout
+(ns^{:doc "Render web pages using Selmer tamplating markup."
+      :author "Simon Brooke"}
+   youyesyet.layout
   (:require [selmer.parser :as parser]
             [selmer.filters :as filters]
             [markdown.core :refer [md-to-html-string]]
@@ -12,6 +14,7 @@
 (parser/add-tag! :csrf-field (fn [_ _] (anti-forgery-field)))
 (filters/add-filter! :markdown (fn [content] [:safe (md-to-html-string content)]))
 
+
 (defn render
   "renders the HTML template located relative to resources/templates"
   [template & [params]]
@@ -26,6 +29,7 @@
           :version (System/getProperty "youyesyet.version"))))
     "text/html; charset=utf-8"))
 
+
 (defn error-page
   "error-details should be a map containing the following keys:
    :status - error status

src/clj/youyesyet/middleware.clj

@@ -1,4 +1,6 @@
-(ns youyesyet.middleware
+(ns ^{:doc "Plumbing, mainly boilerplate from Luminus."
+      :author "Simon Brooke"}
+  youyesyet.middleware
   (:require [youyesyet.env :refer [defaults]]
             [clojure.tools.logging :as log]
             [youyesyet.layout :refer [*app-context* error-page]]

src/clj/youyesyet/routes/administrator.clj

@@ -0,0 +1,11 @@
+(ns  ^{:doc "Routes/pages available to administrators, only."
+      :author "Simon Brooke"}
+  youyesyet.routes.administrator
+  (:require [clojure.java.io :as io]
+            [clojure.walk :refer [keywordize-keys]]
+            [compojure.core :refer [defroutes GET POST]]
+            [noir.response :as nresponse]
+            [noir.util.route :as route]
+            [ring.util.http-response :as response]
+            [youyesyet.layout :as layout]
+            [youyesyet.db.core :as db]))

src/clj/youyesyet/routes/authenticated.clj

@@ -1,4 +1,6 @@
-(ns youyesyet.routes.authenticated
+(ns ^{:doc "Routes/pages available to all authenticated users."
+      :author "Simon Brooke"}
+  youyesyet.routes.authenticated
   (:require [clojure.java.io :as io]
             [clojure.walk :refer [keywordize-keys]]
             [compojure.core :refer [defroutes GET POST]]

src/clj/youyesyet/routes/home.clj

@@ -1,4 +1,5 @@
-(ns youyesyet.routes.home
+(ns ^{:doc "Routes/pages available to unauthenticated users."
+      :author "Simon Brooke"} youyesyet.routes.home
   (:require [clojure.walk :refer [keywordize-keys]]
             [noir.response :as nresponse]
             [noir.util.route :as route]

src/clj/youyesyet/routes/oauth.clj

@@ -1,4 +1,5 @@
-(ns youyesyet.routes.oauth
+(ns ^{:doc "OAuth authentication routes - not finished, does not work yet."
+      :author "Simon Brooke"} youyesyet.routes.oauth
   (:require [compojure.core :refer [defroutes GET]]
             [ring.util.http-response :refer [ok found]]
             [clojure.java.io :as io]

src/clj/youyesyet/routes/services.clj

@@ -1,4 +1,5 @@
-(ns youyesyet.routes.services
+(ns ^{:doc "REST API."
+      :author "Simon Brooke"} youyesyet.routes.services
   (:require [clj-http.client :as client]
             [ring.util.http-response :refer :all]
             [compojure.api.sweet :refer :all]

src/cljc/youyesyet/outqueue.cljc

@@ -1,4 +1,6 @@
-(ns youyesyet.outqueue
+(ns ^{:doc "Queue of messages waiting to be sent to the server."
+      :author "Simon Brooke"}
+  youyesyet.outqueue
   (:require
   #?(:clj [clojure.core]
      :cljs [reagent.core :refer [atom]])))
@@ -41,6 +43,7 @@
                   (reverse items)
                   (list items))})))
 
+
 (defn add!
   "Add this item to the queue."
   [q item]
@@ -49,7 +52,9 @@
            (assoc a :items
              (cons item (:items a))))))
 
-(defn q?
+
+(defn queue?
+  "True if x is a queue, else false."
   [x]
   (try
     (let [q (deref x)
@@ -61,21 +66,25 @@
         #?(:clj (print (.getMessage any))
                 :cljs (js/console.log (str any))))))
 
+
 (defn peek
   "Look at the next item which could be removed from the queue."
   [q]
   (last (:items (deref q))))
 
+
 (defn locked?
   [q]
   (:locked (deref q)))
 
+
 (defn unlock!
   ([q ]
    (unlock! q true))
   ([q value]
    (swap! q (fn [a] (assoc a :locked (not (true? value)))))))
 
+
 (defn lock!
   [q]
   (unlock! q false))
@@ -86,6 +95,7 @@
   [q]
   (count (deref q)))
 
+
 (defn take!
   "Return the first item from the queue, rebind the queue to the remaining
   items. If the queue is empty return nil."
@@ -97,12 +107,13 @@
                (assoc (assoc a :items new-queue) :v item))))
   (:v (deref q)))
 
+
 (defn maybe-process-next
   "Apply this process, assumed to be a function of one argument, to the next
   item in the queue, if the queue is not currently locked; return the value
   returned by process."
   [q process]
-  (if (and (q? q)(not (locked? q)))
+  (if (and (queue? q)(not (locked? q)))
     (try
       (lock! q)
       (let [v (apply process (list (peek q)))]

src/cljs/youyesyet/canvasser_app/ajax.cljs

@@ -1,9 +1,11 @@
-(ns youyesyet.ajax
+(ns ^{:doc "Canvasser app transciever for ajax packets."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.ajax
   (:require [ajax.core :as ajax]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.ajax: transciever for ajax packets.
+;;;; youyesyet.canvasser-app.ajax: transciever for ajax packets.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/core.cljs

@@ -1,4 +1,6 @@
-(ns youyesyet.core
+(ns ^{:doc "Canvasser app navigation and routing."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.core
   (:require cljsjs.react-leaflet
             [ajax.core :refer [GET POST]]
             [goog.events :as events]
@@ -7,21 +9,21 @@
             [reagent.core :as r]
             [re-frame.core :as rf]
             [secretary.core :as secretary]
-            [youyesyet.ajax :refer [load-interceptors!]]
-            [youyesyet.handlers]
-            [youyesyet.subscriptions]
-            [youyesyet.ui-utils :as ui]
-            [youyesyet.views.about :as about]
-            [youyesyet.views.electors :as electors]
-            [youyesyet.views.followup :as followup]
-            [youyesyet.views.issue :as issue]
-            [youyesyet.views.issues :as issues]
-            [youyesyet.views.map :as maps])
+            [youyesyet.canvasser-app.ajax :refer [load-interceptors!]]
+            [youyesyet.canvasser-app.handlers]
+            [youyesyet.canvasser-app.subscriptions]
+            [youyesyet.canvasser-app.ui-utils :as ui]
+            [youyesyet.canvasser-app.views.about :as about]
+            [youyesyet.canvasser-app.views.electors :as electors]
+            [youyesyet.canvasser-app.views.followup :as followup]
+            [youyesyet.canvasser-app.views.issue :as issue]
+            [youyesyet.canvasser-app.views.issues :as issues]
+            [youyesyet.canvasser-app.views.map :as maps])
   (:import goog.History))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.core: core of the app.
+;;;; youyesyet.canvasser-app.core: core of the app.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/handlers.cljs

@@ -1,7 +1,9 @@
-(ns youyesyet.handlers
+(ns ^{:doc "Canvasser app event handlers."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.handlers
   (:require [cljs.reader :refer [read-string]]
             [re-frame.core :refer [dispatch reg-event-db]]
-            [youyesyet.db :as db]
+            [youyesyet.canvasser-app.state :as db]
             ))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

src/cljs/youyesyet/canvasser_app/state.cljs

@@ -1,8 +1,10 @@
-(ns youyesyet.db)
+(ns ^{:doc "Canvasser app client state."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.state)
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.db: the state of the app.
+;;;; youyesyet.canvasser-app.state: the state of the app.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/subscriptions.cljs

@@ -1,4 +1,6 @@
-(ns youyesyet.subscriptions
+(ns ^{:doc "Canvasser app event subscriptions."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.subscriptions
   (:require [re-frame.core :refer [reg-sub]]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

src/cljs/youyesyet/canvasser_app/ui_utils.cljs

@@ -1,4 +1,6 @@
-(ns youyesyet.ui-utils
+(ns ^{:doc "Canvasser app user interface widgets."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.ui-utils
   (:require [reagent.core :as r]
             [re-frame.core :as rf]))
 

src/cljs/youyesyet/canvasser_app/views/about.cljs

@@ -1,11 +1,13 @@
-(ns youyesyet.views.about
+(ns ^{:doc "Canvasser app about panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.about
   (:require [re-frame.core :refer [reg-sub subscribe]]
             [markdown.core :refer [md->html]]
-            [youyesyet.ui-utils :as ui]))
+            [youyesyet.canvasser-app.ui-utils :as ui]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.views.about: about/credits view for youyesyet.
+;;;; youyesyet.canvasser-app.views.about: about/credits view for youyesyet.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/views/building.cljs

@@ -1,9 +1,11 @@
-(ns youyesyet.views.building
+(ns ^{:doc "Canvasser app households in building panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.building
   (:require [re-frame.core :refer [reg-sub]]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.views.building: building view for youyesyet.
+;;;; youyesyet.canvasser-app.views.building: building view for youyesyet.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/views/electors.cljs

@@ -1,11 +1,13 @@
-(ns youyesyet.views.electors
+(ns ^{:doc "Canvasser app electors in household panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.electors
   (:require [reagent.core :refer [atom]]
             [re-frame.core :refer [reg-sub subscribe dispatch]]
-            [youyesyet.ui-utils :as ui]))
+            [youyesyet.canvasser-app.ui-utils :as ui]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.views.electors: electors view for youyesyet.
+;;;; youyesyet.canvasser-app.views.electors: electors view for youyesyet.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/views/followup.cljs

@@ -1,10 +1,12 @@
-(ns youyesyet.views.followup
+(ns ^{:doc "Canvasser followup request form panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.followup
   (:require [re-frame.core :refer [reg-sub subscribe dispatch]]
-            [youyesyet.ui-utils :as ui]))
+            [youyesyet.canvasser-app.ui-utils :as ui]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.views.followup-request: followup-request view for youyesyet.
+;;;; youyesyet.canvasser-app.views.followup-request: followup-request view for youyesyet.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/views/issue.cljs

@@ -1,8 +1,10 @@
-(ns youyesyet.views.issue
+(ns ^{:doc "Canvasser app current issue detail panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.issue
   (:require [re-frame.core :refer [reg-sub subscribe]]
             [markdown.core :refer [md->html]]
-            [youyesyet.ui-utils :as ui]
-            [youyesyet.views.issues :as issues]))
+            [youyesyet.canvasser-app.ui-utils :as ui]
+            [youyesyet.canvasser-app.views.issues :as issues]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;

src/cljs/youyesyet/canvasser_app/views/issues.cljs

@@ -1,10 +1,12 @@
-(ns youyesyet.views.issues
+(ns ^{:doc "Canvasser app current issues list panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.issues
   (:require [re-frame.core :refer [reg-sub subscribe]]
-            [youyesyet.ui-utils :as ui]))
+            [youyesyet.canvasser-app.ui-utils :as ui]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.views.issues: issues view for youyesyet.
+;;;; youyesyet.canvasser-app.views.issues: issues view for youyesyet.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

src/cljs/youyesyet/canvasser_app/views/map.cljs

@@ -1,10 +1,12 @@
-(ns youyesyet.views.map
+(ns ^{:doc "Canvasser app map view panel."
+      :author "Simon Brooke"}
+  youyesyet.canvasser-app.views.map
   (:require [re-frame.core :refer [reg-sub subscribe dispatch]]
             [reagent.core :as reagent]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
-;;;; youyesyet.views.map: map view for youyesyet.
+;;;; youyesyet.canvasser-app.views.map: map view for youyesyet.
 ;;;;
 ;;;; This program is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU General Public License

test/cljs/youyesyet/canvasser_app/core_test.cljs

@@ -1,7 +1,7 @@
-(ns youyesyet.core-test
+(ns youyesyet.canvasser-app.core-test
   (:require [cljs.test :refer-macros [is are deftest testing use-fixtures]]
             [reagent.core :as reagent :refer [atom]]
-            [youyesyet.core :as rc]))
+            [youyesyet.canvasser-app.core :as rc]))
 
 (deftest test-home
   (is (= true true)))

test/cljs/youyesyet/canvasser_app/doo_runner.cljs

@@ -0,0 +1,6 @@
+(ns youyesyet.canvasser-app.doo-runner
+  (:require [doo.runner :refer-macros [doo-tests]]
+            [youyesyet.canvasser-app.core-test]))
+
+(doo-tests 'youyesyet.canvasser-app.canvasser-app.core-test)
+

test/cljs/youyesyet/doo_runner.cljs

@@ -1,6 +0,0 @@
-(ns youyesyet.doo-runner
-  (:require [doo.runner :refer-macros [doo-tests]]
-            [youyesyet.core-test]))
-
-(doo-tests 'youyesyet.core-test)
-