Skip to content

[Tracking] Documenting Base

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

$ 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:

$ 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 mailing-list, which will warn you if GitLab is going under maintenance.

If you feel like it, you can communicate on Twitter 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. 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. 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:

PS: The linked documentation points to base 4.16.0.0, that is to be shipped with GHC 9.2.1

Adjacent Work

Edited by Hécate Kleidukos
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information