-----------------------------------------------------------------------------
-- |
-- Module : Test
-- Copyright : (c) Simon Marlow 2002
-- License : BSD-style
--
-- Maintainer : libraries@haskell.org
-- Stability : provisional
-- Portability : portable
--
-- This module illustrates & tests most of the features of Haddock.
-- Testing references from the description: 'T', 'f', 'g', 'Visible.visible'.
--
-----------------------------------------------------------------------------
-- This is plain comment, ignored by Haddock.
{-# LANGUAGE Rank2Types, GADTs #-}
module Test (
-- Section headings are introduced with '-- *':
-- * Type declarations
-- Subsection headings are introduced with '-- **' and so on.
-- ** Data types
T(..), T2, T3(..), T4(..), T5(..), T6(..),
N1(..), N2(..), N3(..), N4, N5(..), N6(..), N7(..),
-- ** Records
R(..), R1(..),
-- | test that we can export record selectors on their own:
p, q, u,
-- * Class declarations
C(a,b), D(..), E, F(..),
-- | Test that we can export a class method on its own:
a,
-- * Function types
f, g,
-- * Auxiliary stuff
-- $aux1
-- $aux2
-- $aux3
-- $aux4
-- $aux5
-- $aux6
-- $aux7
-- $aux8
-- $aux9
-- $aux10
-- $aux11
-- $aux12
-- | 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
module Hidden,
-- * A visible module
module Visible,
{-| nested-style doc comments -}
-- * Existential \/ Universal types
Ex(..),
-- * Type signatures with argument docs
k, l, m, o,
-- * A section
-- and without an intervening comma:
-- ** A subsection
{-|
> a literal line
$ a non /literal/ line $
-}
f',
withType, withoutType
) where
import Hidden
import Visible
import Data.Maybe
bla = Nothing
-- | This comment applies to the /following/ declaration
-- and it continues until the next non-comment line
data T a b
= A Int (Maybe Float) -- ^ This comment describes the 'A' constructor
| -- | This comment describes the 'B' constructor
B (T a b, T Int Float) -- ^
-- | An abstract data declaration
data T2 a b = T2 a b
-- | A data declaration with no documentation annotations on the constructors
data T3 a b = A1 a | B1 b
-- A data declaration with no documentation annotations at all
data T4 a b = A2 a | B2 b
-- A data declaration documentation on the constructors only
data T5 a b
= A3 a -- ^ documents 'A3'
| B3 b -- ^ documents 'B3'
-- | Testing alternative comment styles
data T6
-- | This is the doc for 'A4'
= A4
| B4
| -- ^ This is the doc for 'B4'
-- | This is the doc for 'C4'
C4
-- | A newtype
newtype N1 a = N1 a
-- | A newtype with a fieldname
newtype N2 a b = N2 {n :: a b}
-- | A newtype with a fieldname, documentation on the field
newtype N3 a b = N3 {n3 :: a b -- ^ this is the 'n3' field
}
-- | 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 N4 a b = N4 a
newtype N5 a b = N5 {n5 :: a b -- ^ no docs on the datatype or the constructor
}
newtype N6 a b = N6 {n6 :: a b
}
-- ^ docs on the constructor only
-- | docs on the newtype and the constructor
newtype N7 a b = N7 {n7 :: a b
}
-- ^ The 'N7' constructor
class (D a) => C a where
-- |this is a description of the 'a' method
a :: IO a
b :: [a]
-- ^ this is a description of the 'b' method
c :: a -- c is hidden in the export list
c = undefined
-- ^ This comment applies to the /previous/ declaration (the 'C' class)
class D a where
d :: T a b
e :: (a,a)
-- ^ This is a class declaration with no separate docs for the methods
instance D Int where
d = undefined
e = undefined
-- instance with a qualified class name
instance Test.D Float where
d = undefined
e = undefined
class E a where
ee :: a
-- ^ This is a class declaration with no methods (or no methods exported)
-- This is a class declaration with no documentation at all
class F a where
ff :: a
-- | This is the documentation for the 'R' record, which has four fields,
-- 'p', 'q', 'r', and 's'.
data R =
-- | This is the 'C1' record constructor, with the following fields:
C1 { p :: Int -- ^ This comment applies to the 'p' field
, q :: forall a . a->a -- ^ This comment applies to the 'q' field
, -- | This comment applies to both 'r' and 's'
r,s :: Int
}
| C2 { t :: T1 -> (T2 Int Int)-> (T3 Bool Bool) -> (T4 Float Float) -> T5 () (),
u,v :: Int
}
-- ^ This is the 'C2' record constructor, also with some fields:
-- | Testing different record commenting styles
data R1
-- | This is the 'C3' record constructor
= C3 {
-- | The 's1' record selector
s1 :: Int
-- | The 's2' record selector
, s2 :: Int
, s3 :: Int -- NOTE: In the original examples/Test.hs in Haddock, there is an extra "," here.
-- Since GHC doesn't allow that, I have removed it in this file.
-- ^ The 's3' record selector
}
-- These section headers are only used when there is no export list to
-- give the structure of the documentation:
-- * This is a section header (level 1)
-- ** This is a section header (level 2)
-- *** This is a section header (level 3)
{-|
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/>.
-}
f :: C a => a -> Int
-- | we can export foreign declarations too
foreign import ccall g :: Int -> IO CInt
-- | this doc string has a parse error in it: \'
h :: Int
h = 42
-- $aux1 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 @
-- $aux2 This is some documentation that is attached to a name ($aux2)
-- $aux3
-- @ code block on its own in named doc @
-- $aux4
--
-- @ code block on its own in named doc (after newline) @
{- $aux5 a nested, named doc comment
with a paragraph,
@ and a code block @
-}
-- some tests for various arrangements of code blocks:
{- $aux6
>test
>test1
@ test2
test3
@
-}
{- $aux7
@
test1
test2
@
-}
{- $aux8
>test3
>test4
-}
{- $aux9
@
test1
test2
@
>test3
>test4
-}
{- $aux10
>test3
>test4
@
test1
test2
@
-}
-- This one is currently wrong (Haddock 0.4). The @...@ part is
-- interpreted as part of the bird-tracked code block.
{- $aux11
aux11:
>test3
>test4
@
test1
test2
@
-}
-- $aux12
-- > foo
--
-- > bar
--
-- | A data-type using existential\/universal types
data Ex a
= forall b . C b => Ex1 b
| forall b . Ex2 b
| forall b . C a => Ex3 b -- NOTE: I have added "forall b" here make GHC accept this file
| Ex4 (forall a . a -> a)
-- | This is a function with documentation for each argument
k :: 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 function has arg docs but no docs for the function itself
l :: (Int, Int, Float) -- ^ takes a triple
-> Int -- ^ returns an 'Int'
-- | This function has some arg docs
m :: R
-> N1 () -- ^ one of the arguments
-> IO Int -- ^ and the return value
-- | This function has some arg docs but not a return value doc
-- can't use the original name ('n') with GHC
newn :: R -- ^ one of the arguments, an 'R'
-> N1 () -- ^ one of the arguments
-> IO Int
newn = undefined
-- | A foreign import with argument docs
foreign import ccall unsafe
o :: Float -- ^ The input float
-> IO Float -- ^ The output float
-- | We should be able to escape this: \#\#\#
-- p :: Int
-- can't use the above original definition with GHC
newp :: Int
newp = undefined
-- | a function with a prime can be referred to as 'f''
-- but f' doesn't get link'd 'f\''
f' :: Int
-- | Comment on a definition without type signature
withoutType = undefined
-- | Comment on a definition with type signature
withType :: Int
withType = 1
-- Add some definitions here so that this file can be compiled with GHC
data T1
f = undefined
f' = undefined
type CInt = Int
k = undefined
l = undefined
m = undefined