Update database.api.php to remove deprecated db_*() functions.

Problem/Motivation

#2849745: Replace documentation recommending db_*() wrappers is trying to fix all documentation which references db_*() functions.

Let's split out the database.api.php file and fix it, since it is the primary documentation for this API.

Proposed resolution

Fix the documentation in core/lib/Drupal/Core/Database/database.api.php to exclude the deprecated db_*() functions.

Also, this is a good documentation-only candidate for backport to 8.6.x, even during alpha.

Remaining tasks

User interface changes

API changes

Data model changes