Hoogle guides the way with examples

[decentral1se]

What if we could achieve documentation example nirvana just like conj.io and clojuredocs.org. When you search for a function on Hoogle, it gives examples of how to use it!

Idea started on #haskell:

<lwm> folks, does ANYTHING like this exist in Haskell: http://conj.io/
<lwm> I know we have Hoogle ... but this is ... like, cooler
<srhb> lwm: What are you referring to? The reference table?
<lwm> when I put a function there, I get examples of how to use it
<erisco> you're supposed to click through on Hoogle to Hackage and hope there are 
         examples there
<srhb> lwm: Ah. In that case the answer is simple and discouraging: No one bothered 
       to do it. :P
<lwm> erisco: but when there aren't examples (which can be the case!), it sucks
<srhb> Ideally I suppose haddock could be expanded with example sections that hoogle 
       could easily include in the search results
<srhb> Oh, it already has those.
<srhb> lwm: -- | Example header; -- >>> example expression; -- example result
<srhb> lwm: So I guess the trick is to make hoogle steal those examples 
      (perhaps an expandable section underneath the type etc.) and then 
      update ALL OF HACKAGE with actual examples :-)
<lwm> wouldn't that be *so* cool
<lwm> I would love that 
<srhb> lwm: Go start the discussion! https://github.com/ndmitchell/hoogle/issues

It's a crazy idea.

Say, I would search how to use the head function. I'd go on Hoogle and type it in. I would be brought to the results page and from clicking on the first link head :: [a] -> a, I would be brought to the usual link, but instead see something like:

head :: [a] -> a

λ. head [1,2,3]
1

λ. head $ reverse "hoogle"
'e'

Extract the first element of a list, which must be non-empty.

From the conj.io about page:

continued to evolve and with thanks to now features examples sourced from ClojureDocs as well as user submitted content.

User submitted content would be so rad.

[ndmitchell]

Certainly, more docs and examples are always useful! I'm a particular fan of docs that are also tests, so you even know they are correct.

I think if the examples were in Haddock, they'd already be showing up in Hoogle, see http://hoogle.haskell.org/?hoogle=splitOn%20%2Bextra for an example. If there was a decently sized collection of examples somewhere (e.g. a git repo in some regularised form) I'd be fine with scraping and integrating that. So I don't think Hoogle is the bottleneck - point me at some useful content (or first create it, or get people to collaborate it and create it) and I'm happy to pick it up. That also goes for relevant tutorials that mention things, basically any kind of function name augmentation that is scrapable.

[decentral1se]

Fantastic. Hoogle can already do this.

For the function usage examples we could copy what clojuredocs.org seems to be doing. Check out the page for the peek function. There are two user submitted examples! I will have a chat with those clojuredocs folks to see how they get things working. It would be nice to have a repo and just accept pull requests on different files and then you could parse from there.

As for the tutorials ... that would be cool too.

So, what is the important information? The function name, type and examples. Any preferences on a parse-able format?

[ndmitchell]

So it's important to give the complete name - it's not just head, it's base Prelude.head. Other than that, try picking an existing format - e.g. the Haddock markup - for the files.

If you want user examples, you probably want a web UI for people to enter them, some gentle review, and to generate the output of the examples automatically (so they are guaranteed correct).

[decentral1se]

That sounds like solid advice.

I am really liking this clojuredocs.org project. It's a good place to start taking ideas from.

OK, Ill be back in 3 months with something 😄

[ndmitchell]

Be sure to share whatever you've got as soon as you have it - it seems like a great idea and I wish you the best of luck.

[decentral1se]

I just got linked to the documentation patches of Michael Orlitzky which went directly into GHC using doctest! For example, Hoogle is already giving us the examples for the maybe function of patch D561. So, I am going to submit some patches and see if I can't some others to do it as well. Let's see how it goes 👍

[ndmitchell]

Good luck! FWIW, I find doctest formatted output to be a bit verbose, and tend to write my own custom doctester (e.g. https://hackage.haskell.org/package/extra-1.4.3/docs/Data-List-Extra.html#v:chunksOf), but certainly very welcome.