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).
Yeh. Problem with `@api private` is that they are still displayed in the API documentation and there are no flags to disable that. I explicitly don't want this for internal APIs so I think we should just be `@private`. Any objections to that line of thinking?