# Documenting a Handler

There are some [hints in](/development/handlers/development/#readme) on how to structure the README.md, but
more details can't hurt.

Each handler should have some documentation. This is done in the README.md. The layout and contents is inspired
by Unix manual pages. These pages are also converted _into_ manual pages via `go generate`. (See the man/
sub- directory).

That README.md should have the following layout:

For the title use `# Name` (literally that string), in that section use `_handler_ - what the hander does`

Then a `# Description` section, telling what the handler does and other useful information.

Then a `# Syntax` section detailing how to use the handler in the configuration.

Potentially a `# Examples` section with examples. If code blocks are labeled `corefile` a test will check if
those snippets are valid.

If there are metrics begin gathered the README.md must have a `# Metrics` section detailing those, if
something is added to the context a `# Context` section must be there.

Finally and optionally you can add a `# Notes`, `# Bugs` or `# See Also` section if you like.

For styling use this:

- The name of the handler in the running text should be italic: _handler_.
- User supplied arguments in the running text reference use strong text: **EXAMPLE** and capitals.
- Optional text is in block quotes: [optional].
- Use three dots to indicate multiple options are allowed: dbhost [FILE]....
  Item used literal: literal.

If domain name are used use: example.org or example.net. For IP addresses use 198.51.100.1 and 2001:db8::1.

So to recap, this would like this:

```markdown
# Name

_handler_ - what is does

# Description

Description of what it does.

# Syntax

How to use it in the Conffile and what options are available.

# Examples

Examples of using it in a configuration, use `~~~conffile` is you want this check by a test.

# Metrics

Used if the handler has metrics.

# Context

Used if the handler adds to the context.

# Notes

Any notes. Also optional.

# Bugs

Any bugs you know off?

# See Also

Other references material that could be useful.
```