Tutorial: Haddock

About

Haddock is a documentation generator, which means that if code is written using a certain style of comments, then Haddock can generate user-friendly HTML explaining it, along with various other kinds of documentation files. It's effectively JavaDoc for Haskell.

Installation

1. Run stack install haddock from command prompt, terminal, etc, after switching to the courseography folder.

Generation

1. Run stack exec haddock -- -o x -h y from command prompt, terminal, etc. x is the location of your output, and y is the location is the location of the file that you want to generate documentation from. If /output is the output, just use output to fix the problem.

Pro Tip #1: If switched to some folder, called some_folder, to generate documentation from file, called some_file.hs, if some_file.hs depends on some other file, called other_file.hs, then if the command stack exec haddock -- -o output -h some_file.hs is run from command prompt while in some_folder, then other_file.hs will not be included in the scope, and the result will be an error. To fix this, navigate up a folder and run stack exec haddock -- -o some_folder/output -h some_folder/some_file.hs.

Pro Tip #2: Generating your output to a folder included in the .gitignore will keep you from having to keep track of accidentally adding your Haddock output to a commit!

Comment-Style

It is a bit redundant to include everything, see the Haddock User Guide, so instead the two most useful Haddock practices are included below. A function is done using the following format:

-- |Function description.
function

A module header that doesn't include all possible fields for a module header is done using the following format:

{-|
    Module      : some_module
    Description : Some short description.

A bigger description of some_module, potentially a rant on how there isn't a convention for the tense of your Haddock
comments.
-}

Useful Links

• Haddock User Guide