docs: various cleanups
Continuation of the work to make the docs a bit better. See the commits for details. There are still some usages of the deprecated
annotation that I think it is better to drop once those APIs are no longer used/removed in the future, what do you think?