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

None

Activity

Show:
gfredericks
August 6, 2014, 9:04 PM

Attached a new patch.

Rich Hickey
October 9, 2015, 2:04 PM

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.

Andy Fingerhut
October 24, 2015, 8:25 PM

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.

Alex Miller
October 25, 2015, 3:07 AM

I'm working on this.

Alex Miller
September 22, 2016, 7:42 PM

incomplete and I (still) own this one

Assignee

Alex Miller

Reporter

import

Approval

Vetted

Patch

Code

Affects versions

Priority

Minor
Configure