IdP 3.4: Deprecated items in custom Syntax

[Rod Widdowson]

I'm purposely limiting this to something I can do on my own, but there is an obvious extension....

There was a question in JIRA recently explicitly about deprecated syntax in the attribute resolver and whether can one know the
precise list of things which will be deprecated.

Thus far our deprecation efforts have been concentrated on documenting what is deprecated in its usual location and emitting a
warning when it is encountered.  This will be great for individual deployers, but for people preparing documentation for their users
(which is a set which much commonality to consortium members) it falls a bit short.   So it seems to me that a list of deprecated
(and removed) elements (alongside their replacement) would be extremely useful.

Further it would be very easy to produce in a one-off fashion (by looking for the DeprecationSupport class).  

The definite downside is that we would now have the "this is deprecated" information in two places and the system programmer in me
hates that (since one can be wrong and that is a worse situation than having no information).

Nonetheless I would like, for the custom syntax, to pull together a list of deprecated items and their replacements.  Since I tend
to be the most active in this code I would have no issue with trying to keep it up to date, but I still feel that such a page needs
to be marked as "advisory" with the definitive statement always being found in the individual pages.

Does anyone think that this is a bad idea?

Does anyone have any observations about the wider problem and how/whether to document it?

Does anyone have suggestions of where to put such page(s)?

Thanks

Rod