formula: add/improve more API docs.

Shouldn't be anything controversial here but just want to get more @Homebrew/owners :eyes: on it. We're getting there (slowly).
i will be landing a patch that removes this method soon (it's only remaining use is inside this class, and it will eventually be replaced by an array of urls rather than a single string)