Borrow multiple structs mutable from State

[Saethox]

Closes #86

Adds two methods to State:

• get_multiple_mut() (previously get_many()) returns up to eight different mut refs to CustomState's, given they are different.
• get_states_mut() returns the MutState struct, which implements pretty much the same methods as State (except insert and the parent methods, but including the convenience methods), but allows simultaneously accessing multiple mut refs to different CustomState, with the restriction that each CustomState can only be borrowed once.

Example usage of get_multiple_mut() can be found in AcoGeneration, and usage of get_states_mut() in SimpleEvaluator.

[luleyleo]

This does look good over all, but it definitely needs more documentation.

Once it's properly documented, and the macro for convenience functions does not hamper formatting, we can merge this.

[luleyleo]

The indentation seems to be a bit messed up. Furthermore, I'm tempted to implement all of this as a trait. If formatting works inside this macro, it should be okay, but if not, using a trait would be better.

[Saethox]

Using a trait has the disadvantage that MutState requires &mut self even for non-mutable access (because the type is inserted into the internal type set), so a trait bundling the convenience methods needs to borrow self mut on, e.g., population_stack(). This consequently means borrowing State mut for population_stack() even when it's not needed, which could be kind of annoying when accessing the stack multiple times read-only.

I guess we could implement the convenience methods for each struct separately, but this just means trading off auto-formatting on a small code snippet against duplicated code and documentation.

This is why I ultimately settled on a macro, because the convenience methods are not expected to be frequently touched, and adding a new method just means making sure exactly once that the formatting is right.

[luleyleo]

Hmm that's annoying. I don't think there is a nice way to deal with this then.

[luleyleo]

The fact that every type can only be borrowed once, even if the states reference gets dropped before, should be documented clearly.

[Saethox]

Yeah, I forgot a bunch of documentation in several places.

[luleyleo]

Note that currently neither MutState nor MultiStateTuple are public, and thus their documentation is hidden as well.

[luleyleo]

Both MutState and MultiStateTuple are still private. It's best to always compile and check the documentation to make sure all links are working and everything looks good.

[Saethox]

You're right, I forgot that framework::state is not public. Running cargo doc also revealed some other broken links and images in the documentation, so we might want to also fix that. I think an issue for reviewing the documentation in general is appropriate, as most methods and structs lack it.

Edit: Added #96.

[luleyleo]

Yeah we will have to review the documentation as a whole.

But MultiStateTuple is still private. Could you export that as well, then we can merge this.

[Saethox]

This was actually deliberate, as State::get_multiple_mut already has enough documentation in my opinion. Or does leaving MultiStateTuple private conflict with some visibility guideline in some way? If so, I will change it.

[luleyleo]

Unless we have a good reason to keep it private (i.e. we want to have a sealed trait, which is why Rust allows this), it should be public if it's part of our api.

[luleyleo]

Looks good