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).
My understanding is that `@private` is a stand-in for places where you can't mark something as private using the built-in visibility-changing methods; this is `@api private`.