[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:
- Insert the following snippet of text at the end of the description:
Tracking: https://gitlab.haskell.org/ghc/ghc/issues/17929
; - 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);
- Insert the
~documentation
label. You can use the quick action/label ~documentation
at the end of the MR's description; - Set the milestone to the next release;
- 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:
-
Control.Applicative -
Data.Function -
Control.Monad -
Data.Bifoldable -
Data.Bitraversable -
Data.Coerce -
Data.Foldable -
Non-total functions are not marked as such -
maximumBy
andminimumBy
do not document the case where every element compared is the same.
-
-
Data.Traversable -
GHC.Generics -
Type.Reflection -
Control.Monad.IO.Class -
Data.List -
Data.List.NonEmpty -
Data.Semigroup
PS: The linked documentation points to base
4.16.0.0, that is to be shipped with GHC 9.2.1