Add deprecation warning to Function Trait Type

[aaronayres35]

Fixes #1215
I can open a separate issue about fixing up the Method Trait Type (see #1215 (comment)) if this PR is merged.

This issue was not on the 6.2 milestone, and if we do not want to add this before the 6.2 release I am happy to delay this PR.

This PR declares the Function trait type as deprecated in its doc string, but does not actually raise a deprecation warning yet. It also adds a footnote mentioning the deprecation/linking to the api docs on the "Defining Traits" page in the table of predefined traits next to Function.

Checklist

• Tests
• Update API reference (docs/source/traits_api_reference)
• Update User manual (docs/source/traits_user_manual)
• [ ] Update type annotation hints in traits-stubs

[mdickinson]

Thanks for this. The general shape of the changes looks good. I think we should go one way or the other, though - either bite the bullet and actually make Function deprecated, or limit ourselves to offering advice on using Callable instead, and not actually say that the class is deprecated.

I did find a number of uses of Function in existing (including current) projects, so actual deprecation would be somewhat disruptive.

So I'd suggest that we go with what's here, except that we:

• remove the .. deprecated directive (but keep the contents of that directive; maybe change .. deprecated to .. note)
• keep the Function [3] note, but change it to say that in most cases Callable should be used instead

As a compromise, and to motivate people to move away from Function, we could also say either in the docstring, or in the note (or both) that the Function trait type "may be deprecated in the future".

[mdickinson]

Okay, looking harder, I'm changing my mind again. (Sorry.) Let's be bold and actually deprecate this beast.

I'll contact directly the projects that are using Function to give them some warning.

@aaronayres35 Would you be able to add actual deprecation and tests for this PR?

[aaronayres35]

@aaronayres35 Would you be able to add actual deprecation and tests for this PR?

Sure thing!

[mdickinson]

LGTM

[mdickinson]

I can open a separate issue about fixing up the Method Trait Type

Yes, please! That one may be even easier to deprecate; I suspect we have close to zero uses of it out in the wild.