aboutsummaryrefslogtreecommitdiff
path: root/html-test/src/Test.hs
diff options
context:
space:
mode:
Diffstat (limited to 'html-test/src/Test.hs')
-rw-r--r--html-test/src/Test.hs422
1 files changed, 422 insertions, 0 deletions
diff --git a/html-test/src/Test.hs b/html-test/src/Test.hs
new file mode 100644
index 00000000..d352f029
--- /dev/null
+++ b/html-test/src/Test.hs
@@ -0,0 +1,422 @@
+-----------------------------------------------------------------------------
+-- |
+-- 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.
+
+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
+
+-- ^ 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