Documentation; preparation for beta release.

src/adl_support/core.clj

@@ -1,4 +1,7 @@
-(ns adl-support.core
+(ns ^{:doc "Application Description Language support - utility functions likely
+      to be useful in user-written code."
+      :author "Simon Brooke"}
+  adl-support.core
   (:require [clojure.core.memoize :as memo]
             [clojure.data.json :as json]
             [clojure.java.io :as io]

src/adl_support/filters.clj

@@ -1,4 +1,7 @@
-(ns adl-support.filters
+(ns ^{:doc "Application Description Language support - custom Selmer filters
+      used in generated templates."
+      :author "Simon Brooke"}
+  adl-support.filters
     (:require [clojure.string :as s]
               [selmer.filters :as f]
               [selmer.parser :as p]))

src/adl_support/forms_support.clj

@@ -1,4 +1,7 @@
-(ns adl-support.forms-support
+(ns ^{:doc "Application Description Language support - functions useful in
+      generating forms."
+      :author "Simon Brooke"}
+  adl-support.forms-support
   (:require [adl-support.core :refer :all]
             [adl-support.utils :refer [descendants-with-tag safe-name singularise]]
             [clojure.core.memoize :as memo]
@@ -49,6 +52,7 @@
 
 
 (defmacro get-current-value
+  "Use the function `f` and these `params` to fetch an `entity` record from the database."
   [f params entity-name]
   `(let
      [message# (str "Error while fetching " ~entity-name " record " ~params)]
@@ -59,6 +63,9 @@
 
 
 (defmacro get-menu-options
+  "Fetch options for a menu of `entity-name` from the database, using this
+  `get-q` query and this `list-q` query, using the key `fk`, where the current
+  value is this `value`."
   [entity-name get-q list-q fk value]
   `(remove
     nil?
@@ -107,6 +114,8 @@
 
 
 (defn property-defaults
+  "Get a map of property names and default values for all properties of this
+  `entity` which have explicit defaults."
   [entity]
   (reduce
     merge {}

src/adl_support/print_usage.clj

@@ -1,4 +1,6 @@
-(ns adl-support.print-usage
+(ns ^{:doc "Application Description Language support - print a usage message."
+      :author "Simon Brooke"}
+  adl-support.print-usage
   (:require [clojure.string :refer [join]]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

src/adl_support/rest_support.clj

@@ -1,4 +1,7 @@
-(ns adl-support.rest-support
+(ns ^{:doc "Application Description Language support - functions useful in
+      generating JSON route handlers."
+      :author "Simon Brooke"}
+  adl-support.rest-support
   (:require [adl-support.core :refer [do-or-log-error do-or-return-reason]]
             [clojure.core.memoize :as memo]
             [clojure.data.json :as json]

src/adl_support/tags.clj

@@ -1,4 +1,7 @@
-(ns adl-support.tags
+(ns ^{:doc "Application Description Language support - custom Selmer tags used
+      in generated templates."
+      :author "Simon Brooke"}
+  adl-support.tags
     (:require [selmer.parser :as p]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

src/adl_support/utils.clj

@@ -1,4 +1,4 @@
-(ns ^{:doc "Application Description Language support library - utility functions."
+(ns ^{:doc "Application Description Language support - utility functions."
       :author "Simon Brooke"}
   adl-support.utils
   (:require [adl-support.core :refer [*warn*]]
@@ -86,6 +86,7 @@
 
 
 (defn sort-by-name
+  "Sort these `elements` by their `:name` attribute."
   [elements]
   (sort #(compare (:name (:attrs %1)) (:name (:attrs %2))) elements))
 
@@ -266,8 +267,10 @@
 
 
 (defn pretty-name
-  [entity]
-  (capitalise (singularise (:name (:attrs entity)))))
+  "Return a version of the name of this `element` (entity, field,
+  form, list, page, property) suitable for use in text visible to the user."
+  [element]
+  (capitalise (singularise (:name (:attrs element)))))
 
 
 (defn safe-name