Ross, thanks a lot for the feedback. Sorry I'm late with the response. --- ross@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?for...
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