function `@return`s

[pearsonca]

Many exported functions have no @return documentation. By eye, it seems like many of them shouldn't be exported (i.e., they are internal interface, not capability you want to provide users), but even internal functions benefit from a @return explanation.