(#1255) - Improve API documentation

Adds better documentation for the query()
API and harmonizes our usage of
terminology and punctuation.