ndmitchell:

Hi

...

The deadline is Wednesday, December 6th.

That's incredibly soon, two days is just not enough time to do anything! I recommend a minimum deadline of a week for anything, some people may only catch up with their Haskell mail a couple of times a week.

As for your patch, I think its great, and its exactly the type of thing that should be in the libraries documentation for pretty much everything. My only suggestion would be to include the "corner" cases:

take 3 [1] = [1] drop 3 [1] = []

(ditto splitAt)

i.e. show that they produce a result, not an error.

In general, what do people think about adding examples by default to anything we want in the libraries? Are people ok with this? If so, we should add some guidelines for their constructoin: I.e. * general cases * corner cases and for some things, like the monad transformers: * entire programs Seem reasonable? If so, i'll add some notes to the documentation suggetions. -- Don

| I think what is really needed is for Haddock to have some kind of | "show source" link that shows the source for a function inline in the | documentation without opening a new page. Often the best documentation | for a function is its definition. I believe that Simon M has already implemented exactly that. I'm not sure whether it takes extra flags or what. Simon

Neil Mitchell wrote:

Hi

...

| I think what is really needed is for Haddock to have some kind of | "show source" link that shows the source for a function inline in the | documentation without opening a new page. Often the best documentation | for a function is its definition.

I believe that Simon M has already implemented exactly that. I'm not sure whether it takes extra flags or what.

He has implemented something similar, see http://www-users.cs.york.ac.uk/~ndm/projects/filepath/System-FilePath-Versio...

for an example - click on the source link and it hops to the right place (using HsColour to colourise and tag the source file).

Much as I'd like to take the credit, it was Duncan Coutts who implemented that feature :)

I was more thinking of an "AJAX style" thing where the documentation appears in the same page, rather than linking to a separate page which contains it.

That would certainly be neat. Maybe it could be implemented in Haskell using YHC's JavaScript backend? (half-joking...) AJAX requires a server, and the nice thing about Haddock documentation is you can view it with file:// URLs. Maybe there's a way around this though, I'm not an AJAX expert. Cheers, Simon

Neil Mitchell wrote:

Hi

...

That would certainly be neat. Maybe it could be implemented in Haskell using YHC's JavaScript backend? (half-joking...)

Thats how Hoogle 4 is going to be implemented...

...

AJAX requires a server, and the nice thing about Haddock documentation is you can view it with file:// URLs. Maybe there's a way around this though, I'm not an AJAX expert.

By "AJAX style" I meant:

<a href="javascript:show_code('map')">Show Code</a> <div id="code_map" style="display:none;"> code for map goes here </div>

No need for a server,

Right, that would be easier. I'm a bit concerned that the concept of "the code for a function" is not as simple as it seems. Including just the code for the function itself often won't be useful, because it might be something like myFunction x y z = myFunction' x y z [] so then do we include the transitive closure of code referenced by the function? What if we refer to something in a different file, or scattered around the current file? What about CPP? Presumably functions that are documented elsewhere should be rendered as links. etc. etc. Just linking to a point in the source file is much easier. Making the "include source code" feature optional on a per-function basis would probably make sense, though. Cheers, Simon

On 05/12/06, Simon Marlow wrote:

I'm a bit concerned that the concept of "the code for a function" is not as simple as it seems. Including just the code for the function itself often won't be useful, because it might be something like

myFunction x y z = myFunction' x y z []

so then do we include the transitive closure of code referenced by the function? What if we refer to something in a different file, or scattered around the current file? What about CPP? Presumably functions that are documented elsewhere should be rendered as links. etc. etc.

My vote for myFunction would be to just show the RHS, but link myFunction' to its own documentation and source link. A nice touch would be to automatically expand the source section of the target function if the user followed a link from another function's source. -- -David House, dmhouse@gmail.com