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.

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