diff options
Diffstat (limited to 'testsuite/tests/haddock/haddock_examples')
7 files changed, 587 insertions, 0 deletions
diff --git a/testsuite/tests/haddock/haddock_examples/Hidden.hs b/testsuite/tests/haddock/haddock_examples/Hidden.hs new file mode 100644 index 0000000000..d30925b10e --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/Hidden.hs @@ -0,0 +1,4 @@ +-- #hide +module Hidden where +hidden :: Int -> Int +hidden a = a diff --git a/testsuite/tests/haddock/haddock_examples/Makefile b/testsuite/tests/haddock/haddock_examples/Makefile new file mode 100644 index 0000000000..9101fbd40a --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/Makefile @@ -0,0 +1,3 @@ +TOP=../../.. +include $(TOP)/mk/boilerplate.mk +include $(TOP)/mk/test.mk diff --git a/testsuite/tests/haddock/haddock_examples/Test.hs b/testsuite/tests/haddock/haddock_examples/Test.hs new file mode 100644 index 0000000000..8336cb543d --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/Test.hs @@ -0,0 +1,407 @@ +----------------------------------------------------------------------------- +-- | +-- 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', + ) where + +import Hidden +import Visible + +-- | 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) + +@ + 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 "header.h" 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 "header.h" + 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 + + +-- 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 diff --git a/testsuite/tests/haddock/haddock_examples/Visible.hs b/testsuite/tests/haddock/haddock_examples/Visible.hs new file mode 100644 index 0000000000..cad719315f --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/Visible.hs @@ -0,0 +1,3 @@ +module Visible where +visible :: Int -> Int +visible a = a diff --git a/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr b/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr new file mode 100644 index 0000000000..ddc289f161 --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr @@ -0,0 +1,159 @@ +[1 of 3] Compiling Visible ( Visible.hs, Visible.o )
+
+==================== Parser ====================
+module Visible where
+visible :: Int -> Int
+visible a = a
+
+
+[2 of 3] Compiling Hidden ( Hidden.hs, Hidden.o )
+
+==================== Parser ====================
+module Hidden where
+hidden :: Int -> Int
+hidden a = a
+
+
+[3 of 3] Compiling Test ( Test.hs, Test.o )
+
+==================== Parser ====================
+<document comment>
+module Test (
+ <IEGroup: 1>, <IEGroup: 2>, T(..), T2, T3(..), T4(..), T5(..),
+ T6(..), N1(..), N2(..), N3(..), N4, N5(..), N6(..), N7(..),
+ <IEGroup: 2>, R(..), R1(..), <document comment>, p, q, u,
+ <IEGroup: 1>, C(a, b), D(..), E, F(..), <document comment>, a,
+ <IEGroup: 1>, f, g, <IEGroup: 1>, <IEDocNamed: aux1>,
+ <IEDocNamed: aux2>, <IEDocNamed: aux3>, <IEDocNamed: aux4>,
+ <IEDocNamed: aux5>, <IEDocNamed: aux6>, <IEDocNamed: aux7>,
+ <IEDocNamed: aux8>, <IEDocNamed: aux9>, <IEDocNamed: aux10>,
+ <IEDocNamed: aux11>, <IEDocNamed: aux12>, <document comment>,
+ <IEGroup: 1>, module Hidden, <IEGroup: 1>, module Visible,
+ <document comment>, <IEGroup: 1>, Ex(..), <IEGroup: 1>, k, l, m, o,
+ <IEGroup: 1>, <IEGroup: 2>, <document comment>, f'
+ ) where
+import Hidden
+import Visible
+<document comment>
+data T a b
+ = <document comment> A Int Maybe Float |
+ <document comment> B (T a b, T Int Float)
+<document comment>
+data T2 a b = T2 a b
+<document comment>
+data T3 a b = A1 a | B1 b
+data T4 a b = A2 a | B2 b
+data T5 a b = <document comment> A3 a | <document comment> B3 b
+<document comment>
+data T6
+ = <document comment> A4 |
+ <document comment> B4 |
+ <document comment> C4
+<document comment>
+newtype N1 a = N1 a
+<document comment>
+newtype N2 a b = N2 {n :: a b}
+<document comment>
+newtype N3 a b = N3 {n3 :: a b <document comment>}
+<document comment>
+newtype N4 a b = N4 a
+newtype N5 a b = N5 {n5 :: a b <document comment>}
+newtype N6 a b = <document comment> N6 {n6 :: a b}
+<document comment>
+newtype N7 a b = <document comment> N7 {n7 :: a b}
+class D a => C a where { a :: IO a; b :: [a]; c :: a; }
+<document comment>
+class D a where { d :: T a b; e :: (a, a); }
+<document comment>
+instance D Int where
+ { d = undefined
+ e = undefined }
+instance Test.D Float where
+ { d = undefined
+ e = undefined }
+class E a where { ee :: a; }
+<document comment>
+class F a where { ff :: a; }
+<document comment>
+data R
+ = <document comment>
+ C1 {p :: Int <document comment>,
+ q :: forall a. a -> a <document comment>,
+ r :: Int <document comment>,
+ s :: Int <document comment>} |
+ <document comment>
+ C2 {t :: T1
+ -> (T2 Int Int) -> (T3 Bool Bool) -> (T4 Float Float) -> T5 () (),
+ u :: Int,
+ v :: Int}
+<document comment>
+data R1
+ = <document comment>
+ C3 {s1 :: Int <document comment>,
+ s2 :: Int <document comment>,
+ s3 :: Int <document comment>}
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+f :: C a => a -> Int
+<document comment>
+foreign import ccall safe "static header.h g" g :: Int -> IO CInt
+<document comment>
+h :: Int
+h = 42
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+<document comment>
+data Ex a
+ = forall b. C b => Ex1 b |
+ forall b. Ex2 b |
+ forall b. C a => Ex3 b |
+ Ex4 forall a. a -> a
+<document comment>
+k ::
+ T () () <document comment>
+ -> (T2 Int Int) <document comment>
+ -> (T3 Bool Bool -> T4 Float Float) <document comment>
+ -> T5 () () <document comment> -> IO () <document comment>
+l :: (Int, Int, Float) <document comment> -> Int <document comment>
+<document comment>
+m :: R -> N1 () <document comment> -> IO Int <document comment>
+<document comment>
+newn :: R <document comment> -> N1 () <document comment> -> IO Int
+newn = undefined
+<document comment>
+foreign import ccall unsafe "static header.h o" o
+ :: Float <document comment> -> IO Float <document comment>
+<document comment>
+newp :: Int
+newp = undefined
+<document comment>
+f' :: Int
+data T1 =
+f = undefined
+f' = undefined
+type CInt = Int
+k = undefined
+l = undefined
+m = undefined
+
+
+
+Test.hs:32:9: Warning: `p' is exported by `p' and `R(..)'
+
+Test.hs:32:12: Warning: `q' is exported by `q' and `R(..)'
+
+Test.hs:32:15: Warning: `u' is exported by `u' and `R(..)'
+
+Test.hs:38:9: Warning: `a' is exported by `a' and `C(a, b)'
diff --git a/testsuite/tests/haddock/haddock_examples/header.h b/testsuite/tests/haddock/haddock_examples/header.h new file mode 100644 index 0000000000..0125eb3bfd --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/header.h @@ -0,0 +1,5 @@ + +/* These are used in Test.hs */ +extern int g(HsInt x); +extern HsFloat o(HsFloat x); + diff --git a/testsuite/tests/haddock/haddock_examples/test.T b/testsuite/tests/haddock/haddock_examples/test.T new file mode 100644 index 0000000000..856bf73bfd --- /dev/null +++ b/testsuite/tests/haddock/haddock_examples/test.T @@ -0,0 +1,6 @@ +test('haddock.Test', + [omit_ways(['optasm', 'profasm']), + extra_clean(['Test.hi', 'Test.o', 'Hidden.hi', 'Hidden.o', + 'Visible.hi', 'Visible.o'])], + multimod_compile, + ['Test Hidden Visible', '-XRank2Types -XExistentialQuantification -haddock -ddump-parsed']) |