[Haskell-cafe] Documenting strictness properties for Data.Map.Strict

[Twan van Laarhoven]

On 18/11/11 06:44, Johan Tibell wrote:
> On Thu, Nov 17, 2011 at 9:21 PM, Johan Tibell<johan.tibell at gmail.com>  wrote:
>> I'm not entirely happy with this formulation. I'm looking for
>> something that's clear (i.e. precise and concise, without leaving out
>> important information), assuming that the reader already knows how
>> lazy evaluation works at a high level.
>>
>> Ideas?
>
> This reads a bit better to me:

I actually much prefer the original formulation. In particular, you 
should keep examples together with the rules they illustrate.

> * key and value function arguments passed to functions are
>   evaluated to WHNF before the function body is evaluated, and

"function arguments passed to functions" sounds a bit redundant. Either 
say "arguments passed to functions" or "function arguments". Also 
"before the function body is evaluated" says something about evaluation 
order, does that really matter for strictness?

  * All key and value arguments passed to functions are
    evaluated to WHNF before the function body is evaluated


 >  * keys and values returned by high-order function arguments are
 >    evaluated to WHNF before they are inserted into the map.

Keys and values not returned by higher order functions, but passed in 
directly are also evaluated to WHNF (per the first rule), so that 
qualification is unnecessary. Just say:

   * keys and values are evaluated to WHNF before they are
     inserted into the map.

I also think 'stored' is better here than 'inserted', because the latter 
might give the impression that it only applies to the insert function, 
and not to things like map.


>       insertWith (+) k undefined m  ==  undefined
 >       etc.

As Roman suggested, use = here instead of ==.

To really illustrate the first rule, insertWith (+) is not enough, you 
would really need a function that doesn't use the value, so

     insertWith (\new old -> old) k undefined m = undefined

But that is just nitpicking.


Twan