Data.Map, Data.IntMap documentation

[Andriy Palamarchuk]

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?
Andriy


       
____________________________________________________________________________________
Boardwalk for $500? In 2007? Ha! Play Monopoly Here and Now (it's updated for today's economy) at Yahoo! Games.
http://get.games.yahoo.com/proddesc?gamekey=monopolyherenow