weavejester / medley

A lightweight library of useful Clojure functions
Eclipse Public License 1.0
870 stars 67 forks source link

Remove the use of 'the' in assoc-some docstring #48

Closed mbutlerw closed 4 years ago

mbutlerw commented 4 years ago

Use of 'the' might imply 'value' refers to the value stored under the key, rather than the parameter. Removing it less ambiguously conveys the behaviour of assoc-some.

Could be just me who reads it this way.

I'm also not sure my change is the correct one, but I think it does at least clear up the ambiguity.

Cheers

weavejester commented 4 years ago

What about:

Associates a key, k, with a value, v, in a map, m, if and only if v is not nil.
mbutlerw commented 4 years ago

Yeah i did consider using the symbols, that is the most explicit, just worried that it might not fit the style of the other docstrings. If you don't see that as an issue then great.

This could be an alternative formatting although either works for me:

Associates a key (k) with a value (v) in a map (m) if and only if v is not nil.

Happy to update the commit to whatever you'd prefer :)

weavejester commented 4 years ago

Let's do:

Associates a key k, with a value v in a map m, if and only if v is not nil.

As that's consistent with the style used in other docstrings.