[Documentation]: clarify mutability of collections rather than variables
- Dominant language
- Jupyter Notebook
- Stars
- 7.3k
- Forks
- 833
- Avg merge
- 5h 11m
- Merged PRs (30d)
- 5
Description
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` rather than `vector`.
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.
Contributor guide
Assessment
This issue has not been assessed yet.