Thank you for your interest in documenting the Haskell standard library, aka. `base`. ## Goals This is the tracking issue for documenting `base`. This issue is intended to be linked in each MR that would improve the documentation situation in `base` modules, and will list some modules for which lack of documentation is deemed a priority task. You are encouraged to tackle a module if you think you can add something missing, be it examples, unmentioned edge-case, or a direct risk of runtime error (through the use of `error`/`errorWithoutStacktrace`/`throw`/`undefined`, OR the absence of bound-checking, leading to a segfault). ## Building the docs The source of the `base` library is found in the GHC repository in the `libraries/base` đirectory. In order to build the `base` haddocks, please follow the first three steps listed at ghc.dev, and then run ```sh $ hadrian/build -j --freeze1 --flavour=Quick _build/doc/html/libraries/base-4.19.0.0/base.haddock ``` You will then find the index file at `_build/doc/html/libraries/base-4.19.0.0/index.html`. To build the GHC User's Manual, the command is: ```sh $ hadrian/build _build/doc/html/users_guide/index.html ``` You will then find the index file at `_build/doc/html/users_guide/index.html` ## Communication If you wish to discuss this effort or ask for advice, let's have a chat at #haskell-docs on Freenode. You should also subscribe to the [`ghc-devs`](https://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs) mailing-list, which will warn you if GitLab is going under maintenance. If you feel like it, you can communicate on [Twitter](https://twitter.com/search?q=%23HaskellDocs) and the Fediverse with the hashtag `#HaskellDocs`. Finally, as we are operating in the context of the GHC project, you will be required to abide by its [guidelines for respectful communication](https://github.com/ghc-proposals/ghc-proposals/blob/master/GRC.rst). Disagreement fosters debate, but in no way the Haskell Documentation initiative should be used to deny someone's humanity or basic human rights. If you wish to express some concerns about how you are treated in the Haskell discussion and work spaces, you can contact the co-chairs of the GHC Steering Committee, Simon Marlow and Simon Peyton-Jones. Thank you for joining us. :) ## Merge Requests Etiquette When creating a merge request: 1. Insert the following snippet of text at the end of the description: `Tracking: https://gitlab.haskell.org/ghc/ghc/issues/17929`; 2. Mention @core-libraries (by simply writing it out) at the end of the description. This will greatly help the process (you can liberally mention @Kleidukos on the docs MRs); 3. Insert the `~documentation` label. You can use the quick action `/label ~documentation` at the end of the MR's description; 4. Set the milestone to the next release; 5. Include a screenshot of the rendered HTML documentation. Moreover, when inserting examples, please use the [collapsible headers syntax](https://haskell-haddock.readthedocs.io/en/latest/markup.html#headings). This will greatly help readability!\ Also: Due to bitrot and the second law of thermodynamics, it is highly discouraged to link to outside sources such as papers or wiki articles. On the contrary, Haskell Wiki articles should point to the Haddocks, alongside other sources. ## Modules These modules require some special attention, either due to the state of their documentation, their importance for newcomers to the language, or both: - [x] [Control.Applicative](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Control-Applicative.html) - [x] [Data.Function](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Function.html) - [ ] [Control.Monad](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Control-Monad.html) - [x] [Data.Bifoldable](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Bifoldable.html) - [x] [Data.Bitraversable](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Bitraversable.html) - [ ] [Data.Coerce](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Coerce.html) - [ ] [Data.Foldable](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Foldable.html) - [x] Non-total functions are not marked as such - [ ] `maximumBy` and `minimumBy` do not document the case where every element compared is the same. - [x] [Data.Traversable](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Traversable.html) - [ ] [GHC.Generics](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/GHC-Generics.html) - [ ] [Type.Reflection](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Type-Reflection.html) - [x] [Control.Monad.IO.Class](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Control-Monad-IO-Class.html) - [x] [Data.List](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-List.html) - [ ] [Data.List.NonEmpty](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-List-NonEmpty.html) - [ ] [Data.Semigroup](https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.19.0.0-inplace/Data-Semigroup.html) PS: The linked documentation points to `base` 4.16.0.0, that is to be shipped with GHC 9.2.1 ## Adjacent Work * 2020-03-19: [Bugfix in Haddock to show module-level collapsible sections & examples](https://github.com/haskell/haddock/pull/1135) * 2020-03-28: [Fix crash in `haddock-library` on unicode space](https://github.com/haskell/haddock/commit/b0514cc5d53bb37424177d2ba986216a914f8b1c) * 2020-08-22: [Add comments about risks and mitigation of lazy IO](https://github.com/haskell/bytestring/pull/258)