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