Copyright | (c) Simon Marlow 2002
License | BSD-style
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | Safe

Test

Contents

- Type declarations
  - Data types
  - Records
- Class declarations
- Function types
- Auxiliary stuff
- A hidden module
- A visible module
- Existential / Universal types
- Type signatures with argument docs
- A section
  - A subsection

Description

This module illustrates & tests most of the features of Haddock. Testing references from the description: `T`, `f`, `g`, `visible`.

Synopsis

- data T a b
  - = A Int (Maybe Float)
  - | B (T a b, T Int Float)
- data T2 a b
- data T3 a b
  - = A1 a
  - | B1 b
- data T4 a b
  - = A2 a
  - | B2 b
- data T5 a b
  - = A3 a
  - | B3 b
- data T6
  - = A4
  - | B4
  - | C4
- newtype N1 a = N1 a
- newtype N2 a b = N2 {
  - n :: a b
  }
- newtype N3 a b = N3 {
  - n3 :: a b
  }
- data N4 a b
- newtype N5 a b = N5 {
  - n5 :: a b
  }
- newtype N6 a b = N6 {
  - n6 :: a b
  }
- newtype N7 a b = N7 {
  - n7 :: a b
  }
- data R
  - = C1 {
    - p :: Int
    - q :: forall a. a -> a
    - r, s :: Int
    }
  - | C2 {
    - t :: T1 -> T2 Int Int -> T3 Bool Bool -> T4 Float Float -> T5 () ()
    - u, v :: Int
    }
- data R1 = C3 {
  - s1 :: Int
  - s2 :: Int
  - s3 :: Int
  }
- class D a => C a where
  - a :: IO a
  - b :: [a]
- class D a where
  - d :: T a b
  - e :: (a, a)
- class E a
- class F a where
  - ff :: a
- f :: C a => a -> Int
- g :: Int -> IO CInt
- hidden :: Int -> Int
- module Visible
- data Ex a
  - = forall b . C b => Ex1 b
  - | forall b . Ex2 b
  - | forall b . C a => Ex3 b
  - | Ex4 (forall a. a -> a)
- k :: T () () -> T2 Int Int -> (T3 Bool Bool -> T4 Float Float) -> T5 () () -> IO ()
- l :: (Int, Int, Float) -> Int
- m :: R -> N1 () -> IO Int
- o :: Float -> IO Float
- f' :: Int
- withType :: Int
- withoutType :: t

# Type declarations

## Data types

data T a b

This comment applies to the following declaration and it continues until the next non-comment line

Constructors

A Int (Maybe Float) | This comment describes the `A` constructor
B (T a b, T Int Float) | This comment describes the `B` constructor

data T2 a b

An abstract data declaration

data T3 a b

A data declaration with no documentation annotations on the constructors

Constructors

A1 a |
B1 b |

data T4 a b

Constructors

A2 a |
B2 b |

data T5 a b

Constructors

A3 a | documents `A3`
B3 b | documents `B3`

data T6

Testing alternative comment styles

Constructors

A4 | This is the doc for `A4`
B4 | This is the doc for `B4`
C4 | This is the doc for `C4`

newtype N1 a

A newtype

Constructors

N1 a |

newtype N2 a b

A newtype with a fieldname

Constructors

N2 |

Fields

n :: a b

newtype N3 a b

A newtype with a fieldname, documentation on the field

Constructors

N3 |

Fields

n3 :: a b

  this is the `n3` field

data N4 a b

An abstract newtype - we show this one as data rather than newtype because the difference isn't visible to the programmer for an abstract type.

newtype N5 a b

Constructors

N5 |

Fields

n5 :: a b

  no docs on the datatype or the constructor

newtype N6 a b

Constructors

N6 | docs on the constructor only

Fields

n6 :: a b

newtype N7 a b

docs on the newtype and the constructor

Constructors

N7 | The `N7` constructor

Fields

n7 :: a b

## Records

data R

This is the documentation for the `R` record, which has four fields, `p`, `q`, `r`, and `s`.

Constructors

C1 | This is the `C1` record constructor, with the following fields:

Fields

p :: Int

  This comment applies to the `p` field

q :: forall a. a -> a

  This comment applies to the `q` field

r, s :: Int

  This comment applies to both `r` and `s`

C2 | This is the `C2` record constructor, also with some fields:

Fields

t :: T1 -> T2 Int Int -> T3 Bool Bool -> T4 Float Float -> T5 () ()
u, v :: Int

data R1

Testing different record commenting styles

Constructors

C3 | This is the `C3` record constructor

Fields

s1 :: Int

  The `s1` record selector

s2 :: Int

  The `s2` record selector

s3 :: Int

  The `s3` record selector

test that we can export record selectors on their own:

# Class declarations

class D a => C a where

This comment applies to the previous declaration (the `C` class)

Methods

a :: IO a

this is a description of the `a` method

b :: [a]

this is a description of the `b` method

class D a where

This is a class declaration with no separate docs for the methods

Methods

d :: T a b

e :: (a, a)

Instances

D Float |
D Int |

class E a

This is a class declaration with no methods (or no methods exported)

Minimal complete definition

ee

class F a where

Methods

ff :: a

Test that we can export a class method on its own:

# Function types

f :: C a => a -> Int

In a comment string we can refer to identifiers in scope with single quotes like this: `T`, and we can refer to modules by using double quotes: Foo. We can add emphasis like this.

- This is a bulleted list
- This is the next item (different kind of bullet)

1. This is an ordered list
2. This is the next item (different kind of bullet)

cat
  a small, furry, domesticated mammal
pineapple
  a fruit grown in the tropics

         This is a block of code, which can include other markup: R
         formatting
                   is
                     significant

    this is another block of code

We can also include URLs in documentation: http://www.haskell.org/.

g :: Int -> IO CInt

we can export foreign declarations too

# Auxiliary stuff

This is some documentation that is attached to a name ($aux1) rather than a source declaration. The documentation may be referred to in the export list using its name.

     code block in named doc

This is some documentation that is attached to a name ($aux2)

     code block on its own in named doc

     code block on its own in named doc (after newline)

a nested, named doc comment

with a paragraph,

     and a code block

    test
    test1

     test2
      test3

    test1
    test2

    test3
    test4

    test1
    test2

    test3
    test4

    test3
    test4

    test1
    test2

aux11:

    test3
    test4

    test1
    test2

    foo

    bar

This is some inline documentation in the export list

    a code block using bird-tracks
    each line must begin with > (which isn't significant unless it
    is at the beginning of the line).

# A hidden module

hidden :: Int -> Int

# A visible module

module Visible

nested-style doc comments

# Existential / Universal types

data Ex a

A data-type using existential/universal types

Constructors

forall b . C b => Ex1 b |
forall b . Ex2 b |
forall b . C a => Ex3 b |
Ex4 (forall a. a -> a) |

# Type signatures with argument docs

k

Arguments

:: T () () | This argument has type `T`
-> T2 Int Int | This argument has type 'T2 Int Int'
-> (T3 Bool Bool -> T4 Float Float) | This argument has type `T3 Bool Bool -> T4 Float Float`
-> T5 () () | This argument has a very long description that should hopefully cause some wrapping to happen when it is finally rendered by Haddock in the generated HTML page.
-> IO () | This is the result type

This is a function with documentation for each argument

l

Arguments

:: (Int, Int, Float) | takes a triple
-> Int | returns an `Int`

m

Arguments

:: R |
-> N1 () | one of the arguments
-> IO Int | and the return value

This function has some arg docs

o

Arguments

:: Float | The input float
-> IO Float | The output float

A foreign import with argument docs

# A section

## A subsection

    a literal line

$ a non literal line $

f' :: Int

a function with a prime can be referred to as `f'` but f' doesn't get link'd 'f\''

withType :: Int

Comment on a definition with type signature

withoutType :: t

Comment on a definition without type signature