(defn some-function
  {:metadoc/examples [(example "Simple" (+ 1 2 3))]}
  [])

(add-examples some-function
  (example "Another example" (some-function 1 2 3)))

(defsnippet my-snippet "Description" (f 1 2))

(example-snippet "Use snippet to sum something" my-snippet +) ;;=> 3
(example-snippet "Use snippet to multiply somenting" my-snippet *) ;;=> 2

Attach unit examples to your vars.

Unit examples are small executable code snippets, images, urls or any data which can illustrate usage of your functions.
Term "unit" means that example should be connected directly to given function.

### Usage

There are several types of examples (macro - type - description):

* [[example]] - `:simple` - simple executable code, can be converted to test
* [[example-session]] - `:session` - list of executable code lines
* [[example-image]] - `:image` - image url
* [[example-url]] - `:url` - just any url
* [[example-snippet]] - `:snippet` - define function which is passed to snippet. Result of snippet call is result of such example. Result can be interpreted as other example type. See below for concrete snippet call. Snippets are created with [[defsnippet]] macro.

Example is just a map with following fields:

* `:type` - type of example
* `:example` - formatted code(s) as a text or just text (for [[example-url]] and [[example-image]])
* `:example-fn` - code(s) as functions (code is evaluated during documentation creation phase)
* `:test-value` - if you want to convert your `:simple` example to test this field keeps expected value (test is run during evaluation phase)
* `:snippet-name` - only for `:snippet` type, name of the snippet function created with [[defsnippet]] macro.
* `:dispatch-result` - only for `:snippet` type, how to treat result of example evaluation

#### Adding examples - inline

You can add examples directly to your metadata under `:examples` tag as a list of `(example...)` macro calls.

```
(defn some-function
  {:metadoc/examples [(example "Simple" (+ 1 2 3))]}
  [])
```

Or call [[add-examples]] macro, pass variable name and examples.

```
(add-examples some-function
  (example "Another example" (some-function 1 2 3)))
```

#### Adding examples - separate namespace

You can put your examples into separate `<your-project>/example/` folder in separate namespaces. Such examples are loaded during documentation generation.

#### Snippets

Sometimes you want to show your example as simple function which should be evaluated by other, more complicated code. Eg. you want to generate some math function plots, calculate something or process data. And you want to reuse such code several times in you example. 

```
(defsnippet my-snippet "Description" (f 1 2))

(example-snippet "Use snippet to sum something" my-snippet +) ;;=> 3
(example-snippet "Use snippet to multiply somenting" my-snippet *) ;;=> 2
```

[[defsnippet]] creates private function which accepts function (code from your example will be passed), `params` as a list and `opts` list which currently contains one element, `md5-hash` of example code.

`opts` are created by framework but `params` are provided when using `example-snippet` macro.

#### Details

* Each example code is wrapped in the function which has an access to `md5-hash` value. It's a hash of formatted example string.
* Snippet can be marked as `:hidden` if you don't want to show it in documentation.
* Result of snippet can be changed to other example type, this way you can easily convert result to image or url.

### Evaluation

Evaluate given example based on type.

[[evaluate]] function is multimethod with dispatch on example type. When you create your own example macro you need also create corresponding evaluation function.

### Rendering

Render to given format.

Call multimethod [[format-example]] with format type as a dispatch. Currently supported are:

* `:html`
* `:markdown` (not implemented yet)
* `:text` (not implemented yet)

Each formatting function is also multimethod `format-...` with dispatch on example type.

Again, if you want to write different formatter - just add corresponding multimethods.

Read metadata from given namespace.

Return information extracted from variables' metadata. Currently supported:

* constants
* examples and snippets
* categories

Documentation writer that outputs HTML.