Hi Sunjay,

Are there any modules with good code examples that I should use as a reference? I want to include both the code and output of the example as if the user was running ghci. Are there any guidelines for contributing documentation?

I would suggest to use the doctest style so that your examples can be automatically tested. I would like to move the test suites of the containers library to doctest. --Kazu

Hi Sunjay,

If I use the doctest style, do I use ">>>" for the prompt? That's more a Python thing. Maybe ">" would be more appropriate for Haskell?

You should use ">>>". If you don't know doctest for Haskell, please read: https://github.com/sol/doctest#readme The following document would also help: https://github.com/kazu-yamamoto/unit-test-example/blob/master/markdown/en/t... --Kazu

There are lots of examples in the lens package. I can't think of a better model. On Wed, Jan 4, 2017 at 1:36 PM, Sunjay Varma wrote:

Hi all, Are there any modules with good code examples that I should use as a reference? I want to include both the code and output of the example as if the user was running ghci. Are there any guidelines for contributing documentation?

Thanks! Sunjay

On Jan 4, 2017 9:20 AM, "Matthew Pickering" wrote:

I think this will be welcomed, go for it!

All patches should be submitted on Phabricator. There are some straightforward instructions on how to submit a patch on the wiki - https://ghc.haskell.org/trac/ghc/wiki/Phabricator

If you want to build the documentation then you can modify mk/build.mk and add the line HADDOCK_DOCS = YES (and probably enable the quick build flavour by uncommenting the line).

Message back if you need help or #ghc on freenode.

Matt

On Wed, Jan 4, 2017 at 2:14 PM, Sunjay Varma wrote:

...

Hi, I'm considering contributing examples to the documentation. I wanted to start with something like Data.List because it is one of the modules I end up using the most. I think a few examples for each function would help users understand them better. I find myself referring back to books like learn you a haskell because I don't remember exactly what I'm supposed to do with a function.

Doing one module seems like a good start and hopefully we can have some other people begin to add their own examples too.

Is this a worthwhile contribution? I haven't contributed before and so I think it's prudent to ask before I add something no one wants.

Are there any examples of modules with good code examples that I should use as a reference? I want to include both the code and output of the example as if the user was running ghci. Are there any guidelines for contributing documentation?

When I say Data.List, I really mean Data.Foldable and Data.Traversable since that is where the functions are actually implemented.

I noticed the GitHub repo said that Pull Requests were okay for easy to review documentation changes. Can I open a pull request there or should I follow another process?

Please let me know when you can. I don't have an exact timeline for when this will be done, but hopefully I'll have something in the next few weeks. I don't anticipate that it will take long once I sit down to do it.

I've always complained about a lack of examples and never done anything about it. Hopefully I can practice what I preach and contribute some in order to make the documentation a little better for everyone.

Thanks for helping to make this language so great! Sunjay

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

On 05.01.2017 00:01, Ben Gamari wrote:

Sunjay Varma writes:

...

Hi, I'm considering contributing examples to the documentation. I wanted to start with something like Data.List because it is one of the modules I end up using the most. I think a few examples for each function would help users understand them better. I find myself referring back to books like learn you a haskell because I don't remember exactly what I'm supposed to do with a function.

Doing one module seems like a good start and hopefully we can have some other people begin to add their own examples too.

Is this a worthwhile contribution? I haven't contributed before and so I think it's prudent to ask before I add something no one wants.

This would be amazing! Many people have remarked that GHC's library documentation is in need of examples; we just need someone to step up and start contributing patches.

...

Are there any examples of modules with good code examples that I should use as a reference? I want to include both the code and output of the example as if the user was running ghci. Are there any guidelines for contributing documentation?

I think Edward's lens library is probably a good example here. I know of few good examples in GHC itself.

And `lens` also uses `doctest` to actually verify the examples. Let's keep in mind that GHC might want to doctest examples too at some point. If any have ideas how that can happen (also having QuickCheck tests and doctests would be great too), I can try to implement that.

...

When I say Data.List, I really mean Data.Foldable and Data.Traversable since that is where the functions are actually implemented.

These are great places to start.

...

I noticed the GitHub repo said that Pull Requests were okay for easy to review documentation changes. Can I open a pull request there or should I follow another process?

We prefer to take patches on Phabricator. However, to lower the barrier to small patches like this I have suggested in the past that we accept GitHub pull requests for small changes.

...

Please let me know when you can. I don't have an exact timeline for when this will be done, but hopefully I'll have something in the next few weeks. I don't anticipate that it will take long once I sit down to do it.

Great. Let us know if you encounter friction.

...

I've always complained about a lack of examples and never done anything about it. Hopefully I can practice what I preach and contribute some in order to make the documentation a little better for everyone.

Thanks for helping to make this language so great! And thanks to you for helping as well!

Cheers,

- Ben

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs