[CLJ-1474] `reduced` docstring should be more explicit Created: 25/Jul/14 Updated: 25/Jul/14 Resolved: 25/Jul/14
|Affects Version/s:||Release 1.6|
|Reporter:||Jean Niklas L'orange||Assignee:||Unassigned|
The documentation for reduced is as follows:
From what I gather, this does not specify whether the init value of a reduce could be a reduced value or not. As shown, the fact that the init value is a reduced value is ignored:
The documentation should explicitly mention that a reduce call will not check if the initial value is reduced.
|Comment by Alex Miller [ 25/Jul/14 9:09 AM ]|
reduced creates a value that has special meaning as the output of invocation of the reducing function. Your example is about an input to that function. I don't see that this makes sense or needs documenting.
You can of course invent a situation where a (reduced 1) input is also the output but again, that seems like a pretty weird use case.
|Comment by Jean Niklas L'orange [ 25/Jul/14 12:10 PM ]|
Right, that's my point. Nowhere in the documentation does it state that this does not apply to the initial value given to reduce. While you and I know this, I don't see how one can conclude this based on the current documentation.
Put differently, someone might wrongly assume that reduce is implemented as an optimised version of this:
However, that's not the case, which I think is worth pointing out.
|Comment by Alex Miller [ 25/Jul/14 5:01 PM ]|
But it might apply to the initial value (as in my example where a reduced value is respected - note that doesn't return (reduced 1), just 1). Your suggested documentation change is talking about input values, but in my mind that leads to incorrect conclusions.
The only change that would make sense to me is clarifying where a "reduced" value is checked (on the result of applying the function passed to reduce). I think that's already implicit in the existing doc string myself. Since we have multiple implementations of "reduce", we have to tread carefully not to refer to explicitly to a particular one.
This use of a reduced initial value does not even make sense; why we would we confuse the docstring to warn about it?