API - Soft-deprecate civicrm_api() wrapper

[colemanw]

Overview

Mildly suggest people shouldn't use this old function that we've been recommending against for years.

[civibot]

Thank you for contributing to CiviCRM! ❤️ We will need to test and review the PR. 👷

Introduction for new contributors

• If this is your first PR, an admin will greenlight automated testing with the command ok to test or add to whitelist.
• A series of tests will automatically run. You can see the results at the bottom of this page (if there are any problems, it will include a link to see what went wrong).
• A demo site will be built where anyone can try out a version of CiviCRM that includes your changes.
• If this process needs to be repeated, an admin will issue the command test this please to rerun tests and build a new demo site.
• Before this PR can be merged, it needs to be reviewed. Please keep in mind that reviewers are volunteers, and their response time can vary from a few hours to a few weeks depending on their availability and their knowledge of this particular part of CiviCRM.
• A great way to speed up this process is to "trade reviews" with someone - find an open PR that you feel able to review, and leave a comment like "I'm reviewing this now, could you please review mine?" (include a link to yours). You don't have to wait for a response to get started (and you don't have to stop at one!) the more you review, the faster this process goes for everyone 😄
• To ensure that you are credited properly in the final release notes, please add yourself to contributor-key.yml
• For more information about contributing, see CONTRIBUTING.md.

Quick links for reviewers

• ➡️ Demo site for this PR
• 📖 Review standards
• 🗒️ Review template (brief or verbose)

[totten]

Yeah, I agree most general usage should go through civicrm_apiX() (because it's easier for downstream users to shoot themselves in the foot with civicrm_api()) -- and it's nice for the IDE to warn people away.

OTOH, @deprecated is often interpreted as: "We plan to remove this, so do anything you can to eliminate references to it." In other words, @deprecated creates de-facto TODOs on all existing callers (where each requires some mix of re-evaluating edge-cases, testing, peer-review, etc) For civicrm_api(), I kinda suspect those TODOs would be counterproductive.

Maybe use the softer @ineternal? Or maybe use @deprecated with stronger guidance?

 * @deprecated
 *    The original `civicrm_api()` is disfavored for typical business-logic/hooks/forms/etc.
 *    The newer `civicrm_api3()` and `civicrm_api4()` provide an Exception-based protocol
 *    that fits better in these contexts. However, if an existing caller handles  `civicrm_api()`
 *    errors, then there is no functional benefit to reworking it.
 *    `civicrm_api()` is often the wrong choice, but it's not planned for removal anytime soon.

[colemanw]

Ok @totten I've incorporated your suggestions and did a bit more API docblock cleanup while I was at it.

[totten]

Looks good to me. Thanks @colemanw.