doc: improve `--pending-deprecation` documentation

This implements steps 1-2 from #18417 (closed):

1. --pending-deprecation is being mentioned in COLLABORATOR_GUIDE.md#deprecations as a subset of doc-deprecation.
2. --pending-deprecation is being mentioned in doc/api/deprecations.md, and the deprecations that support it are explicitly labeled as such (currently, there is only one).

Checklist

• make lint-md passes
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc