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