Data.Map, Data.IntMap documentation

[Sebastian Sylvan]

On 15/08/07, Andriy Palamarchuk <apa3a at yahoo.com> wrote:
> Ross, thanks a lot for the feedback.
> Sorry I'm late with the response.
>
> --- ross at soi.city.ac.uk wrote:
>
> > I rather liked having the complexity at the start of
> > the description:
> > it allows one to find this important information at
> > a glance.
>
> My rationale was that the complexity information,
> while  important, is probably one of the last things
> most of the people are looking for.
> I doubt anybody would e.g. search for all the O(log n)
> operations ;-)
>
> I'll keep the complexity information at the end of
> description unless there are more votes against this.
>
> > Personally I prefer precise specifications of the
> > behavior to examples
> > (and think that examples leave less room on my
> > screen for specs of other
> > functions), but clearly tastes vary.
>
> Agree that the description spec should be precise on
> its own and about differences in tastes.
>
> > But I think it's important that
> > examples be an optional addition to the main
> > description: one should be
> > able to determine the behavior from the description
> > alone.
> ...
> > The examples
> > are there to help, but if one has to use them guess
> > what the function will
> > do in some case then the description is faulty.
>
> Completely agree. In a few cases I improved
> descriptions too.
>
> My goal was not to provide missing information in the
> examples, but have complete functions specification in
> both - examples and text descriptions, so whatever you
> just said would still hold true if you swapped
> "examples" with "description" ;-)
>
> I consider examples to be complimentary to a
> description, but in general of the same importance.
> Each of these forms of behavior specification has its
> own advantages depending on a situation.
> The very fact of having two forms of specifications
> can help in understanding.
>
> This is like having a description of a programming
> language and its formal grammar. One can be used to
> debug and understand another.
>
> > So I'd favour setting off
> > the examples at the end of each function
> > description,
>
> What do you mean?
> Isn't this how it is already?
> http://hackage.haskell.org/trac/ghc/attachment/ticket/1611/Data-Map.html?format=raw#v%3AfromAscList
>
> > and making them more
> > concise by presenting them as equations.
>
> I considered this. I did not make the examples in form
> of equations because in this particular case a map
> programmatic specification
>
>    fromList [(5,"a"), (3,"b")]
>
> is more noisy and less readable than its string
> presentation
>
>    {3:="b",5:="a"}
>
> Example - in my documentation we have this:
>
>    let m = fromList [(5,"a"), (3,"b")]
>    m
>      {3:="b",5:="a"}
>    map (++ "x") m
>      {3:="bx",5:="ax"}
>
> The equation form would be
>
>    (map (++ "x") (fromList [(5,"a"), (3,"b")])) ==
> (fromList [(5,"ax"), (3,"bx")])
>
> IMHO in the first case it is easier to understand.
>
> > My ideal would be if Haddock
> > could present each examples part as initially hidden
> > but expandable with a click.
>
> My personal preference is to keep them together.
>
> What do you think?

Examples take more real-estate than descriptions (most often) and are
also less precise (most often). I'd also prefer to have it hidden if
possible (e.g. some java script collapsible frame or something). Most
of the time I just look at the name, read the description, and
together with the type I have everything I need, so there's no reason
to have to scroll through lots of examples that are only occasionally
required.

-- 
Sebastian Sylvan
+44(0)7857-300802
UIN: 44640862