Documentation: Examples and cleanup for GHC.List (i.e. most of Data.List)
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)
- "laws" or things that should always be true use a simple code block (
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