added return types to make autocomplete and docs easier to use

Adding the `:return:` statement can help certain editors (and Sphinx for that matter) to understand where to link to.