refactor(zone): add return types & doc

@jbdeboer can you please review this PR (should be quick).

The added documentation is mainly targeted for the end-user and comes from a suggestion on the ml.