google / google/flax

[Documentation]: clarify mutability of collections rather than variables

Open
#1,616 2 comments 2 reactions 1 assignee Claimed by @levskaya View on GitHub
Priority: P2 - no schedule
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.