Data.Map, Data.IntMap documentation
apa3a at yahoo.com
Wed Aug 15 15:26:33 EDT 2007
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)
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
> 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
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
What do you mean?
Isn't this how it is already?
> 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
fromList [(5,"a"), (3,"b")]
is more noisy and less readable than its string
Example - in my documentation we have this:
let m = fromList [(5,"a"), (3,"b")]
map (++ "x") m
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?
Boardwalk for $500? In 2007? Ha! Play Monopoly Here and Now (it's updated for today's economy) at Yahoo! Games.
More information about the Libraries