introduce constants for option keys and fix docs

Introduce constants for the options array keys used. Rename 'fields' to
'field_values' as that is a bit more verbose and future proof. Adjusted
api docs to be a bit more concise.