Add methods adjust(state, rule) and adjust!(state, rule).

[ablaom]

At present we have adjust!(state, eta::Real) to update a learning rate, and there is a version with kwargs to update other (nested) parameters. This PR adds adjust!(state, rule::AbstractRule) and a non-mutating version, adjust(state, rule::AbstractRule) to allow updating the entire embedded rule, to resolve #223.

PR Checklist

• Tests are added
• Documentation, if applicable

[ablaom]

Okay, I have now looked over #202, which seems to have different aim, namely convenience. Here I want complete control: Replace (in one hit) the currently embedded rule (in general, an OptimiserChain) with a new one, remembering all the states. #202 does not appear to provide this.

Fortunately, the current PR and #202 appear to offer non-colliding extensions of the current syntax: In #202 we are adding adjust!(tree, oT::Type, eta::Real), adjust!(tree, oT::Type; kw...),
adjust(r::AbstractRule, oT::Type, eta::Real). This PR adds adjust!(tree, r::AbstractRule), adjust(state, rule::AbstractRule)

I'm happy to rebase this PR off #202 to test there really are no method ambiguities, if there is support for this PR.

If the internal layout of an optimiser state tree is public API (this wasn't obvious to me) then I can live without this PR, but that doesn't seem to me the best solution. By the way, my particular use case is FluxML/MLJFlux.jl#322.

[ablaom]

I've added a test that attempting to adjust the rule to one of different type throws an exception.

[ablaom]

I realise there are a lot of open PRs, but could I get rough estimate of time for review?

Note this PR includes tests and doc updates.