Document advice on which APIs should be preferred

[jberdine]

Maybe I missed something, but it would be helpful if the documentation made it clear which APIs ought to be preferred for new code by plugin authors. For example, should I prefer Extension.V3.declare over Extension.declare? Perhaps there is a generic statement like "prefer the values not in the VN submodules" or "prefer the values in the VN submodule for the largest N" or...?

[NathanReb]

Yes you're right we should document these. For now you can consider that one should always prefer the most recent API, that is prefer the Vn submodule with the largest n if there is one.

All the "older" versions are implemented on top of the newest one and will eventually be removed some day.

I'll add some documentation about that!