Code snippets in documentation would be easier to read with type signatures.
andreasabel opened this issue · comments
See e.g. at https://hackage.haskell.org/package/prettyprinter-1.7.0/docs/Prettyprinter.html
Let’s prettyprint a simple Haskell type definition. First, intersperse -> and add a leading ::,
>>> let prettyType = align . sep . zipWith (<+>) ("::" : repeat "->")
This drops the reader into cold water.
Here I would like to see the type signature for prettyType. (Even more so since I don't know the align, sep and maybe (<+>) functions already.)
(Btw. a Haskell type is usually tree-structured and not just a list of base types. So it is not very intuitive why this is an adequate pretttyType function. Maybe a few more introductory sentences would help.)
P.S.: I read through the whole page and got a good understanding what Prettyprinter is doing. Great documentation!
Here I would like to see the type signature for
prettyType.
Agreed.
(Even more so since I don't know the
align,sepand maybe(<+>)functions already.)
We could add hyperlinks to these identifiers, so can be easily looked up.
(Btw. a Haskell type is usually tree-structured and not just a list of base types. So it is not very intuitive why this is an adequate
pretttyTypefunction. Maybe a few more introductory sentences would help.)
The docs say "Let’s prettyprint a simple Haskell type definition.", but maybe we should be clearer.
P.S.: I read through the whole page and got a good understanding what
Prettyprinteris doing. Great documentation!
Thanks! :)
The »cold water« part of the comment is the key issue here. Since this is the very beginning of the documentation, I think a better example would be great. Now to come up with one that’s nontrivial but easy to understand.
I’ve modified it a bit in 1f0bffe on short notice – the type sig is now there, but a nicer example is still something we should consider.
I’m closing this as resolved. A patch for documentation is always welcome though!