Docstrings for `conj!` and `assoc!` should suggest using the return value; effect not always in-place
Description
The docstrings of both `assoc!` and `conj!` say "Returns coll.", possibly suggesting the transient edit happens (always) in-place, `coll` being the first argument. However, this is not the case and the returned collection should always be the one that's used.
Approach: Replace "Returns coll." with "Returns an updated collection." in `conj!`, `assoc!`, `pop!` docstrings.
Patch: CLJ-1385-reword-docstrings-on-transient-update-funct-2.patch
Screened by: Alex Miller
Environment
Activity
Attached a new patch.
I think it could be clearer still, since we want people to know the original coll might have been affected and returned, and the return must be used for subsequent calls. I think some of the language from the transients page should make it into these docstrings.
Would it be correct to say that the collection passed into pop! conj! assoc! etc. has undefined contents after the operation completes, and only the return value has defined contents?
That kind of strong wording may get people's attention.
I'm working on this.
incomplete and I (still) own this one
Assignee
Reporter
Labels
Approval
Patch
Affects versions
Priority
