This is probably outside the scope of this PR, but I wonder if we should always require an @example for public methods *and* we should have it so public methods must return a valid `@return`.. a public method with an `undefined` return value would be weird.