Data.Map, Data.IntMap documentation

[Andriy Palamarchuk]

Thanks everybody for the feedback.
I'm responding to all the comments at once.
Please let me know if I missed something.

The consensus is to have the complexity information in
the beginning of descriptions. I'll return it back.

--- Sebastian Sylvan <sebastian.sylvan at gmail.com>
wrote:

> 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).

I like this suggestion, but such haddock improvements
are out of scope for this change.
I can, however, remove printing of the initial data to
make the examples more compact, so instead of:

 let m = fromList [(5,'a'), (3,'b'), (7,'c')]
 m
   {3:='b',5:='a',7:='c'}
 ...

it will be:

 let m = fromList [(5,'a'), (3,'b'), (7,'c')]
 ...

The examples are too short to put them in separate
sections at the end of the document, as I did with the
Control.Monad examples.

--- apfelmus <apfelmus at quantentunnel.de> wrote:

> I prefer to know the laws that hold. In 
> other words, I want an infinite amount of examples
> at once.  For instance, the laws
> 
> lookup k' (insert k x m) = Just x    if  k ==> k'
> lookup k' (insert k x m) = lookup k' m   if  k /=>
k'
> 
> uniquely define insert, they are everything you
> _can_ know about insert 
> (from the denotational point of view). And they are
> even shorter than 
> concrete examples (= their special cases).
...

Such formulas can definitely be part of the
description.
I'm relatively new to Haskell. While I trust that the
way you described it are accurate, it takes much more
effort to understand it (especially the parts with
"homomorphisms", "mplus", etc) than to understand what
function does. This is probably not because these
topics are complex, but because I don't know
terminology, not yet fluent with the concepts.
Concrete examples are more useful for a person with
"practical programming" background learning Haskell
libraries, who just wants to start using them.

--- apfelmus <apfelmus at quantentunnel.de> wrote:

> > 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"}
> 
> The joy of Haskell is that the laws themselves can
> be expressed in  Haskell. So I prefer
> 
>    fromList [(5,"a"), (3,"b")]
> 
> over
> 
>    {3:="b",5:="a"}
> 
> since the latter is not a Haskell expression.
> Besides, the haddock 
> neither defines it nor is there at least a  show 
> function or similar 
> that outputs this string representation.

{3:="b",5:="a"} is actually the output of "show"
function from the older GHC version I used when I
started to work on the Data.Map documentation :-)
In the middle of the changes I upgraded to the new
version of Ubuntu, got a newer compiler, which just
prints
"fromList [(3,"b"),(5,"a")]".

I want to collect feedback on your suggestion. Do you
guys prefer this format:

 let m = fromList [(5,'a'), (3,'b')]
 insert 5 'x' m == fromList [(5,'x'), (3,'b')]
 insert 10 'x' m == fromList [(5,'a'), (3,'b'),
(10,'x')]
 insert 5 'x' empty == fromList [(5,'x')]

over this:

 let m = fromList [(5,'a'), (3,'b')]
 insert 5 'x' m
   {3:='b',5:='x'}
 insert 10 'x' m
   {3:='b',5:='a',10:='x'}
 insert 5 'x' empty
   {5:='x'}

apfelmus, the first form is what you want?
Can you suggest any other improvements?

--- Adrian Hey <ahey at iee.org> wrote:

> But I really think this discussion is somewhat moot
> as IMO the entire Data.Map module should be
> deprecated in favour of this..
>
http://darcs.haskell.org/packages/collections-ghc6.6/Data/Map/AVL.hs
> 
> and ultimately this..
>
http://darcs.haskell.org/packages/collections-ghc6.6/Data.Trie.General/Data/Trie/General/Types.hs
> 
> not that I'm in any way biased :-)

I hope that the new Map implementation will at least
have the same level of documentation ;-)

--- Adrian Hey <ahey at iee.org> wrote:

> I found hardest thing about writing the clone was
> figuring out precisely what
> many of the functions did. (In many cases either the
> documentation was
> ambiguous, or it was OK but the implementation was
> not consistent with the docs.)

When writing these docs we found and fixed a couple of
bugs and documentation inconsistencies.

Andriy


      ____________________________________________________________________________________
Luggage? GPS? Comic books? 
Check out fitting gifts for grads at Yahoo! Search
http://search.yahoo.com/search?fr=oni_on_mail&p=graduation+gifts&cs=bz