docstrings for functions in :final deprecation stage are bogus
(documentation 'dont-use-this 'function) =>
The root cause is that attaching documentation to closures affects the underlying simple-fun.
There is simply no place to store the documentation in a closure.
There are three solutions to this problem for deprecation, not the general limitation.
1) Store the documentation in globaldb keyed by the name of the closure.
Now that we have re-nameable closures, this is a cinch. (And again, re-naming is not something to be exposed to users - it works just well enough to do some nice system-internal things, because it changes the identity of the closure, which is undesirable)
2) don't try to use closures to reduce storage size. Just use DEFUN.
3) use a hashtable keyed by the closure. For the more general case this should be a weak hashtable.
It seems to me that (1) is most appropriate here.