 (defn make-key
   "Create a key that can be looked up in a config store (keypin.type/IStore, java.util.Map/Properties or map/vector)
   instance. The following optional keys are supported:
-  :lookup  - The function to look the key up:
-             (fn [the-map the-key validator description value-parser default-value? default-value
-                  (fn not-found-fn [not-found-message])])
-             default: ordinary key look up
-  :parser  - The value parser function (args: key, value)
-  :default - Default value to return if key is not found
-  :sysprop - System property name that can override the config value (before parsing)
-  :envvar  - Environment variable that can override the config value and system property (before parsing)
-  :source  - Source or container (of reference type, e.g. atom/promise etc.) of key/value pairs"
+
+  | Kwarg    | Description                 |
+  |----------|-----------------------------|
+  |`:lookup` |Function to look the key up (details below) - default: [[lookup-key]] - ordinary key look up |
+  |`:parser` |The value parser function `(fn [key value])`                                                 |
+  |`:default`|Default value to return if key is not found                                                  |
+  |`:sysprop`|System property name that can override the config value (before parsing)                     |
+  |`:envvar` |Environment variable that can override the config value and system property (before parsing) |
+  |`:source` |Source or container (of reference type, e.g. atom/agent/promise etc.) of key/value pairs     |
+
+  ## Lookup function
+
+  ```
+  (fn [store key validator description value-parser default-value? default-value not-found-handler])->value
+
+  ;; validator is a predicate function: (fn [parsed-value])->boolean
+  ;; not-found-handler is function (fn not-found-fn [not-found-message]) called when the store does not have the kay
+  ```
+
+  See: [[lookup-key]], [[lookup-keypath]]"
   [the-key validator description {:keys [lookup parser default sysprop envvar source]
                                   :or {lookup lookup-key
                                        parser i/identity-parser}


(defn realize-config
  "Realize config by applying variable substitution, if any.
  Options:
  :logger        (object) instance of keypin.Logger, defaults to printing to *err*
  :config-mapper (object) instance of keypin.Mapper, default: keypin.Mapper/DEFAULT"
  ([config]
    (realize-config config {}))
  ([config {:keys [logger config-mapper]



(defn read-config
  "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?]
