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).
The class-level as opposed to spec-level, yeh? If that's the case: :+1: