update documentation: boolean behaviour

Some documentation updates, as discussed in #1.

(I hope you are ok with the JSON::true, JSON::false suggestion)