I think it would be quite useful to have a @deprecated flag. Unlike @internal, I believe the documentation for the function should actually be generated, but show some notice somewhere that it is deprecated. More specifically, changing a function subheading in the markdown from ### core.init() to ### core.init() (deprecated) comes to mind, but perhaps another layout could look nicer.

Real-world uses of this functionality can be found here and here

Is there any interest in this? I'd be happy to make a PR for this :)