explicitly document that the "authority" API is not recommended to be used.

From a discussion at the QA Hackathon in Lyon.  While $AUTHORITY is exposed as
an API in Class::MOP and it is not intended to be removed (in the near
future), its existence is questionable and its use is not recommended.