There are over 150 deprecated elements in the code that is parsed for the https://api.joomla.org website (basically the libraries directory) that have no descriptions about the deprecation. Ideally, every deprecated element (or its parent if we're talking about an entire class having been deprecated) should have some form of description either pointing to an alternative or indicating that the functionality will not exist or be supported by Joomla in the future (I put the or there because of the number of CMS package deprecations where the "replacement" is installing a package via Composer, though the CMS isn't providing that API anymore Joomla still has an alternative).

Likewise, there are a lot of deprecation notices that need updates (such as those for social APIs where the Framework packages are now deprecated as well, or saying that JKeychain is deprecated without a replacement is inaccurate as the joomla/keychain Framework package is alive and well).

Lastly, with the migration to namespaced classes, it would be ideal for the doc blocks to be updated with the correct references; I'll leave this note to only target deprecations for now to stay in line with the issue's theme but ideally this is a global review sooner or later.