Documentation of Signal.filter is wrong

[jvoigtlaender]

Wrong in two ways.

First:

The general behavior of the function is currently described thus:

Filter out some updates. The given function decides whether we should keep an update. If no updates ever flow through, we use the default value provided.

This does not address/explain what happens in a situation like:

primes : Signal Int -- initial value is 2, then come 3, 5, 7, 11, ... as updates

isOdd : Int -> Bool

oddPrimes : Signal Int
oddPrimes =
    filter isOdd 0 primes

What will happen is that the initial value of oddPrimes is 0. But that does not follow from the documentation. The documentation mentions the "default value" only for the situation that "no updates ever flow through". But here all updates (3, 5, ...) do flow through.

Moreover, it makes a wrong statement about a situation like:

primes : Signal Int -- initial value is 2, then come 3, 5, 7, 11, ... as updates

isEven : Int -> Bool

evenPrimes : Signal Int
evenPrimes =
    filter isEven 0 primes

Since here "no updates ever flow through" (given that all of 3, 5, ... are odd), the documentation predicts that the "default value provided", i.e., 0, is used. But that's not true. Actually, the signal evenPrimes as defined above is equivalent to Signal.constant 2, not to Signal.constant 0.

Second:

After describing the general behavior, the documentation goes on to give an example:

The following example only keeps even numbers and has an initial value of zero.

The example code that is given is this:

numbers : Signal Int

isEven : Int -> Bool

evens : Signal Int
evens =
    filter isEven 0 numbers

But the statement that it (evens) "has an initial value of zero" is wrong. Consider the case numbers = Signal.constant 2. Then evens has initial value 2, not 0.