Skip to content

Documentation: Examples and cleanup for GHC.List (i.e. most of Data.List)

Julien Debon requested to merge Sir4ur0n/ghc:doc/moreDocExamples into master

Followup of !2531 (closed), I passed on all GHC.List functions (i.e. most of Data.List functions). This was actually much more work than I'd originally expected 😆

I also took the opportunity to slightly improve the documentation on how to contribute (the PR + Marge bot process) as I couldn't find any related information (and thus I didn't know what to expect for my first PR, which may also be the case for other new contributors?)

  • Explain the Marge Bot process
  • Fix some typos and a broken link in documentation
  • Add examples to nearly all functions of GHC.List (reexported in Data.List) except for a few exceptions (e.g. strict versions of functions)
  • Add more consistency between examples and "laws":
    • "laws" or things that should always be true use a simple code block (>)
    • examples use Haddock examples (>>> for input, output on next line)

I intend next to pass on modules like Foldable and Traversable: at least add examples, maybe also provide more "newcomer-friendly" words/explanations (e.g. I think explaining a "fold" is also often referred to as "reduce" or "accumulate" helps a lot grasping the concept, and bridges the knowledge gap coming from other languages)

Would you prefer me to propose documentation in this same PR, or in another one?

I let you decide what granularity you wish for these PRs.

Cheers!


Thank you for your contribution to GHC!

Please take a few moments to verify that your commits fulfill the following:

  • are either individually buildable or squashed
  • have commit messages which describe what they do (referring to [Notes][notes] and tickets using #NNNN syntax when appropriate)
  • have added source comments describing your change. For larger changes you likely should add a [Note][notes] and cross-reference it from the relevant places.
  • add a testcase to the testsuite.
  • See above the reasons

Merge request reports