% Blue Blistering Barnacles! % Getty Ritter

The basic idea of blue-blistering-barnacles is that, when looking at documentation in a language like Haskell, you have two questions about a type:

• How can I create it?
• What can I do with it?

Therefore, BBB will ignore the traditional Haddock structure and spit out documentation that will have a page for each type T. Each page will have two sections: Creating and Using. The Creating section will contain - All constructors for T - All defined values of type T - All functions whose return value contains T

On the other hand, the Using section will contain - All other functions that take a T, even if they appeared in the above section

Both of these include instances of typeclasses specialized to T, as well, but maybe hidden behind JavaScript. (TBD: whether to also include every function written in terms of that typeclass.) So, given a source file like

module Sample(S(..), T(..), flip, mkT, sumT, zero) where

newtype S = S { fromS :: Int } deriving (Eq, Show)

instance Monoid S where
  mempty = S 0
  mappend (S x) (S y) = S (x + y)

zero :: S
zero = S 0

data T = Leaf S | Node T T | Nil deriving (Show)

mkT :: [Int] -> T
mkT [] = Nil
mkT [x] = Leaf (S x)
mkT (x:xs) = Node (Leaf (S x)) (mkT xs)

sumT :: T -> Int
sumT Nil = 0
sumT (Leaf (S x)) = x
sumT (Node l r) = sum l + sum r

flip :: T -> T
flip (Leaf s) = Leaf s
flip (Node l r) = Node (flip l) (flip r)

will produce two pages:

newtype S :: *

Creating

• constructor S { fromS :: Int }
• value zero :: S
• typeclass instance Monoid S where
  • value mempty :: S
  • function mappend :: S -> S -> S

Using

• record field fromS :: S -> Int
• typeclass instance Monoid S where
  • function mappend :: S -> S -> S
• typeclass instance Eq S where
  • function (==) :: S -> S -> Bool
  • function (/=) :: S -> S -> Bool
• typeclass instance Show S where
  • function showsPrec :: Int -> S -> ShowS
  • function show :: S -> String
  • function showList :: [S] -> ShowS

data T :: *

Creating

• constructor Leaf :: S -> T
• constructor Node :: T -> T -> T
• function mkT :: [Int] -> T
• function flip :: T -> T

Using

• function flip :: T -> T
• function sumT :: T -> Int
• typeclass instance Show T where
  • function showsPrec :: Int -> T -> ShowS
  • function show :: T -> String
  • function showList :: [T] -> ShowS

We also want to have pages for typeclasses, with typeclass methods in one section, and functions and values that make use of that typeclass in another section, e.g.

class Show a

Methods

• function showsPrec :: Int -> a -> ShowS
• function show :: a -> String
• function showList :: [a] -> String

Functions

• function print :: Show a => a -> IO ()

and so forth.

In generating HTML + JS, we can use fragment identifiers to indicate that a typeclass should also be monomorphized to a particular type, too, e.g. visiting show.html might give you the docs you see above, but visiting show.html#subst_a:Bool would execute some JavaScript that would change the above to

instance Show Bool

Methods

• function showsPrec :: Int -> Bool -> ShowS
• function show :: Bool -> String
• function showList :: [Bool] -> String

Functions

• function print :: Bool -> IO ()