 
 
 (defn read-config
-  "Read config file(s) returning a java.util.Map instance.
-  Options:
-  :parent-key     (string)   key to identify the parent filenames having K/V pairs, default: \"parent.filenames\"
-  :logger         (object)   instance of keypin.Logger, defaults to printing to *err*
-  :config-readers (list/vec) collection of keypin.ConfigIO instances, default: for Properties and EDN files
-  :media-readers  (list/vec) collection of keypin.MediaReader instances, default: for Filesystem and Classpath
-  :realize?       (boolean)  whether realize the template variables in the string, default: true"
+  "Read config file(s) returning a `java.util.Map` instance.
+
+  ## Options
+
+  | Kwarg           | Type     | Description                                  | Default                         |
+  |-----------------|----------|----------------------------------------------|---------------------------------|
+  |`:parent-key`    | string   | key to identify the parent config filenames  | `\"parent.filenames\"`          |
+  |`:logger`        | object   | instance of `keypin.Logger`                  | prints to `*err*`               |
+  |`:config-readers`| list/vec | collection of `keypin.ConfigIO` instances    | for `.properties`, `.edn` files |
+  |`:media-readers` | list/vec | collection of `keypin.MediaReader` instances | for filesystem and classpath    |
+  |`:realize?`      | boolean  | whether realize template variables in string | `true`                          |"
   (^Map [config-filenames]
     (read-config config-filenames {}))
   (^Map [config-filenames {:keys [^String parent-key logger config-readers media-readers realize?]


(defmacro defkey
  "Define one or more keys as vars using argument vectors. Every argument vector must have one of the following arities:
  [key]
  [key options]
  [key validator description]
  [key validator description options]
  See `make-key` for details. First argument to `defkey` can optionally be a base option-map for all argument vectors.
  Examples:
  (defkey
    ip   [:ip-address]
    port [:port #(< 1023 % 65535) \"Server port\" {:parser str->int :default 3000}])
  (defkey
    {:lookup lookup-key}
    ip   [\"server.ip.address\"]
    port [\"server.port\" #(< 1023 % 65535) \"Server port\" {:parser str->int :default 3000}])
  See: make-key"
  [the-sym arg-vec & more]
  (let [options (if (odd? (count more))
                  (i/expect-arg the-sym map? ["Expected an option map, found" (pr-str the-sym)])


(defn write-config
  "Write config to a specified file.

  ## Options

  | Kwarg           | Type     | Description                               | Default                         |
  |-----------------|----------|-------------------------------------------|---------------------------------|
  |`:logger`        | object   | instance of `keypin.Logger`               | prints to `*err*`               |
  |`:config-writers`| list/vec | collection of `keypin.ConfigIO` instances | for `.properties`, `.edn` files |
  |`:escape?`       | boolean  | whether escape values when writing        | `true`                          |"
  ([config-filename config]
    (write-config config-filename config {}))
  ([config-filename config {:keys [logger config-writers escape?]
