Documenting a Handler

There are some hints in 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:

# 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.