lib/options: Update documentation comments for docs generation

Documents functions in `lib.options` for docs generation with nixdoc.

The formatting change in the `mkOption` arguments is due to the way
`nixdoc` parses documentation comments on pattern arguments. It's not
ideal, but it works.