 ;; ----- Slug functions -----
 
 (defn valid-slug?
-  "Return true if the provided-slug is a valid slug and false if not"
+  "Returns `true` if the provided slug is a valid, and `false` if not."
   [provided-slug]
   ;; if the slug is the same one we'd provide for a resource with that name, then it's valid
   (and (string? provided-slug) (= provided-slug (slugify provided-slug)) (not (s/blank? provided-slug))))

;; ----- Validation functions -----

(defn valid-name?
  "Return true if the provided name is a valid name, false if not"
  [n]
  ;; any non-blank string is a valid name
  (and (string? n) (not (s/blank? n))))

;; ----- Properties common to all FCMS resources -----

(def
  reserved-properties
  "Properties of a resource that can't be specified during a create and are ignored during an update."
  #{:id :created-at :updated-at :type :version :links})
(def
  retained-properties
  "Properties of a resource that are retained during an update even if they aren't in the updated property set."
  #{:name :slug :created-at :type})

;; ----- ISO 8601 timestamp -----
