flax
flax copied to clipboard
[Documentation]: clarify mutability of collections rather than variables
Just making a note so we don't forget it - several people have been confused by the existing documentation around mutability, mutable=
kwarg, variables, collections - and on top of that how sow
, capture_intermediates
work.
One thing that sticks out is that we may not be making it clear enough in docs that mutability is about the mutability of the collections and not the variables - as one user put it in C++ parlance we're controlling things more like vector<const string>
rather than vector<string>
.
I've seen confusion on this point a few times, so it might be worth trying to underline how collections and the Variable references work under the hood a little more clearly.
I'm just filing this so that we keep it in mind in our next pass over documentation.