Document handler function semantics (both inputs and outputs)

[vspinu]

Currently the docs of handler argument just state

 handler: A handler function

The semantics of the handlers is confusing. Different documentation pages use different arguments. Some are using function(a=, b=) some are using function(req) or function(req, res), or even a combination function(req, id, name).

The return value is also undocumented. What I could infer from the docs so far, is that if the return is the res object it is treated as such, else it's a body which is encoded with the serializer.