doc: improve --pending-deprecation documentation
#18433
Merged
--pending-deprecation documentation
#18433