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