% 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

```{.haskell}
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 ()`