Better document API expectations

[bsipocz]

It came up recently that we don't document API expectations (e.g #1523), e.g returning NoResultsWarnings for empty results rather than errors, etc.

[pllim]

Just to clarify for future reference, from what I see in the modules the expectation is something like this:

import warnings
from ..exceptions import NoResultsWarning

class Something:
    def query_something(...):
        if no_result:
            warnings.warn('message', NoResultsWarning)
            # return None -- commented because if this is the last line, it already does anyway