Julia: Document @deprecate

[malmaud]

And depwarn

[StefanKarpinski]

In doing so, we should make sure we're happy with their APIs and make sure they work well for non-Base users as well. Do these seem to work pretty well outside of Base? Do we want a different API for choosing whether a deprecation is exported or not? E.g. @deprecate export foo bar or something?

[bjarthur]

what do you mean by "whether a deprecation is exported"?

is there a way to deprecate a function that used to be exported by a module but now is not? a brief effort on my part to make this work has failed.

[StefanKarpinski]

By default @deprecate exports the deprecated name since if the name isn't exported you shouldn't technically need a deprecation. We have, however, provided deprecations for some non-exported names, in which case you don't want to start exporting it when it's deprecated. There is now an optional additional argument to @deprecate that controls this. I still think a keyword-like syntax might be better, however.

[bjarthur]

thanks for the info.

what about the case where sth used to be exported, and now it's not. is there a way to deprecate? the specific use case is https://github.com/GiovineItalia/Gadfly.jl/pull/1050

[cossio]

Any plans to change @deprecate? If not I could prepare a small PR with documentation (basically an example of how to use it).

[TeroFrondelius]

Documentation with an example would help a lot.

[juliohm]

I always forget the syntax, it would be really nice to have deprecation-related macros documented.

[juliohm]

Reviving this issue... We are in Julia 1.1 without a documentation...

@cossio did you have a chance to prepare a PR?

Guess what... I forgot the syntax again. Googling a solution for the 10th time...

[cossio]

Honestly by now I don't remember how it works anymore.
I didn't make that PR in the end because the API was subject to some re-design, which I guess never happened in the end?

[StefanKarpinski]

Someone throw out some API suggestions. Having positional boolean arguments is _not_ a good API design which is why nobody can remember it. A better API would be easier to remember and you wouldn't care so much about the docs (although they should of course exist for a public API).

[omus]

Just a thought. Does @deprecate need to specify if the deprecated name will be exported? Couldn't we do something like:

export foo bar
@deprecate foo bar

[StefanKarpinski]

True, one could just do the export bit separately.

[nickrobinson251]

at-deprecate is now documented, exported and included in the manual (thanks to #29586 and #31226)

Still to be documented are

• depwarn
• at-deprecate_binding
• at-deprecate_moved
• at-deprecate_stdlib
  (although we may or may not want to export all of these)