From b89b21a6d75c5498d4ebc19e8d099c1b91c44182 Mon Sep 17 00:00:00 2001 From: David Waern Date: Mon, 6 Dec 2010 14:25:37 +0000 Subject: Rename golden-tests into html-tests. "golden tests" sounds strange --- tests/html-tests/README | 28 + tests/html-tests/copy.hs | 30 + tests/html-tests/runtests.hs | 115 ++ tests/html-tests/tests/A.hs | 2 + tests/html-tests/tests/A.html.ref | 68 + tests/html-tests/tests/B.hs | 2 + tests/html-tests/tests/B.html.ref | 51 + tests/html-tests/tests/Bug1.hs | 6 + tests/html-tests/tests/Bug1.html.ref | 89 + tests/html-tests/tests/Bug2.hs | 4 + tests/html-tests/tests/Bug2.html.ref | 53 + tests/html-tests/tests/Bug3.hs | 6 + tests/html-tests/tests/Bug3.html.ref | 69 + tests/html-tests/tests/Bug4.hs | 5 + tests/html-tests/tests/Bug4.html.ref | 68 + tests/html-tests/tests/Bug6.hs | 23 + tests/html-tests/tests/Bug6.html.ref | 297 ++++ tests/html-tests/tests/Bug7.hs | 12 + tests/html-tests/tests/Bug7.html.ref | 153 ++ tests/html-tests/tests/Bug8.hs | 17 + tests/html-tests/tests/Bug8.html.ref | 80 + tests/html-tests/tests/Bugs.hs | 3 + tests/html-tests/tests/Bugs.html.ref | 69 + tests/html-tests/tests/CrossPackageDocs.hs | 3 + tests/html-tests/tests/CrossPackageDocs.html.ref | 391 +++++ tests/html-tests/tests/Examples.hs | 34 + tests/html-tests/tests/Examples.html.ref | 150 ++ tests/html-tests/tests/FunArgs.hs | 16 + tests/html-tests/tests/FunArgs.html.ref | 163 ++ tests/html-tests/tests/GADTRecords.hs | 12 + tests/html-tests/tests/GADTRecords.html.ref | 197 +++ tests/html-tests/tests/Hash.hs | 51 + tests/html-tests/tests/Hash.html.ref | 284 ++++ tests/html-tests/tests/Hidden.hs | 6 + tests/html-tests/tests/NamedDoc.hs | 4 + tests/html-tests/tests/NamedDoc.html.ref | 57 + tests/html-tests/tests/NoLayout.hs | 12 + tests/html-tests/tests/NoLayout.html.ref | 71 + tests/html-tests/tests/NonGreedy.hs | 5 + tests/html-tests/tests/NonGreedy.html.ref | 68 + tests/html-tests/tests/QuasiExpr.hs | 34 + tests/html-tests/tests/QuasiExpr.html.ref | 191 +++ tests/html-tests/tests/QuasiQuote.hs | 9 + tests/html-tests/tests/QuasiQuote.html.ref | 53 + tests/html-tests/tests/TH.hs | 8 + tests/html-tests/tests/TH.html.ref | 52 + tests/html-tests/tests/TH2.hs | 8 + tests/html-tests/tests/TH2.html.ref | 44 + tests/html-tests/tests/Test.hs | 414 +++++ tests/html-tests/tests/Test.html.ref | 1968 ++++++++++++++++++++++ tests/html-tests/tests/Ticket112.hs | 9 + tests/html-tests/tests/Ticket112.html.ref | 69 + tests/html-tests/tests/Ticket61.hs | 3 + tests/html-tests/tests/Ticket61.html.ref | 69 + tests/html-tests/tests/Ticket61_Hidden.hs | 7 + tests/html-tests/tests/Ticket75.hs | 7 + tests/html-tests/tests/Ticket75.html.ref | 99 ++ tests/html-tests/tests/TypeFamilies.hs | 28 + tests/html-tests/tests/TypeFamilies.html.ref | 168 ++ tests/html-tests/tests/TypeOperators.hs | 22 + tests/html-tests/tests/TypeOperators.html.ref | 215 +++ tests/html-tests/tests/Visible.hs | 3 + tests/html-tests/tests/Visible.html.ref | 54 + 63 files changed, 6308 insertions(+) create mode 100644 tests/html-tests/README create mode 100644 tests/html-tests/copy.hs create mode 100644 tests/html-tests/runtests.hs create mode 100644 tests/html-tests/tests/A.hs create mode 100644 tests/html-tests/tests/A.html.ref create mode 100644 tests/html-tests/tests/B.hs create mode 100644 tests/html-tests/tests/B.html.ref create mode 100644 tests/html-tests/tests/Bug1.hs create mode 100644 tests/html-tests/tests/Bug1.html.ref create mode 100644 tests/html-tests/tests/Bug2.hs create mode 100644 tests/html-tests/tests/Bug2.html.ref create mode 100644 tests/html-tests/tests/Bug3.hs create mode 100644 tests/html-tests/tests/Bug3.html.ref create mode 100644 tests/html-tests/tests/Bug4.hs create mode 100644 tests/html-tests/tests/Bug4.html.ref create mode 100644 tests/html-tests/tests/Bug6.hs create mode 100644 tests/html-tests/tests/Bug6.html.ref create mode 100644 tests/html-tests/tests/Bug7.hs create mode 100644 tests/html-tests/tests/Bug7.html.ref create mode 100644 tests/html-tests/tests/Bug8.hs create mode 100644 tests/html-tests/tests/Bug8.html.ref create mode 100644 tests/html-tests/tests/Bugs.hs create mode 100644 tests/html-tests/tests/Bugs.html.ref create mode 100644 tests/html-tests/tests/CrossPackageDocs.hs create mode 100644 tests/html-tests/tests/CrossPackageDocs.html.ref create mode 100644 tests/html-tests/tests/Examples.hs create mode 100644 tests/html-tests/tests/Examples.html.ref create mode 100644 tests/html-tests/tests/FunArgs.hs create mode 100644 tests/html-tests/tests/FunArgs.html.ref create mode 100644 tests/html-tests/tests/GADTRecords.hs create mode 100644 tests/html-tests/tests/GADTRecords.html.ref create mode 100644 tests/html-tests/tests/Hash.hs create mode 100644 tests/html-tests/tests/Hash.html.ref create mode 100644 tests/html-tests/tests/Hidden.hs create mode 100644 tests/html-tests/tests/NamedDoc.hs create mode 100644 tests/html-tests/tests/NamedDoc.html.ref create mode 100644 tests/html-tests/tests/NoLayout.hs create mode 100644 tests/html-tests/tests/NoLayout.html.ref create mode 100644 tests/html-tests/tests/NonGreedy.hs create mode 100644 tests/html-tests/tests/NonGreedy.html.ref create mode 100644 tests/html-tests/tests/QuasiExpr.hs create mode 100644 tests/html-tests/tests/QuasiExpr.html.ref create mode 100644 tests/html-tests/tests/QuasiQuote.hs create mode 100644 tests/html-tests/tests/QuasiQuote.html.ref create mode 100644 tests/html-tests/tests/TH.hs create mode 100644 tests/html-tests/tests/TH.html.ref create mode 100644 tests/html-tests/tests/TH2.hs create mode 100644 tests/html-tests/tests/TH2.html.ref create mode 100644 tests/html-tests/tests/Test.hs create mode 100644 tests/html-tests/tests/Test.html.ref create mode 100644 tests/html-tests/tests/Ticket112.hs create mode 100644 tests/html-tests/tests/Ticket112.html.ref create mode 100644 tests/html-tests/tests/Ticket61.hs create mode 100644 tests/html-tests/tests/Ticket61.html.ref create mode 100644 tests/html-tests/tests/Ticket61_Hidden.hs create mode 100644 tests/html-tests/tests/Ticket75.hs create mode 100644 tests/html-tests/tests/Ticket75.html.ref create mode 100644 tests/html-tests/tests/TypeFamilies.hs create mode 100644 tests/html-tests/tests/TypeFamilies.html.ref create mode 100644 tests/html-tests/tests/TypeOperators.hs create mode 100644 tests/html-tests/tests/TypeOperators.html.ref create mode 100644 tests/html-tests/tests/Visible.hs create mode 100644 tests/html-tests/tests/Visible.html.ref (limited to 'tests/html-tests') diff --git a/tests/html-tests/README b/tests/html-tests/README new file mode 100644 index 00000000..fd906b2b --- /dev/null +++ b/tests/html-tests/README @@ -0,0 +1,28 @@ + +This is a testsuite for Haddock that uses the concept of "golden files". That +is, it compares output files against a set of reference files. + +To add a new test: + + 1) Create a module in the "tests" directory. + + 2) Run runtests.hs. You should now have output/.html. The test + passes since there is no reference file to compare with. + + 3) To make a reference file from the output file, do + runhaskell copy.hs + +Tips and tricks: + +You can + runhaskell copy.hs + +to copy all output files into reference files. + +You can + runhaskell runtests.hs all + +to continue despite a failing test. + +You can pass extra options to haddock like so + runhaskell runtests.hs --title="All Tests" all diff --git a/tests/html-tests/copy.hs b/tests/html-tests/copy.hs new file mode 100644 index 00000000..fa18fe9c --- /dev/null +++ b/tests/html-tests/copy.hs @@ -0,0 +1,30 @@ +import System.Cmd +import System.Environment +import System.FilePath +import System.Exit +import System.Directory +import Data.List +import Control.Monad +import Text.Regex + + +main = do + args <- getArgs + dir <- getCurrentDirectory + contents <- getDirectoryContents (dir "output") + if not $ null args + then + mapM copy [ "output" file | file <- contents, ".html" `isSuffixOf` file, takeBaseName file `elem` args ] + else + mapM copy [ "output" file | file <- contents, ".html" `isSuffixOf` file ] + + +copy file = do + let new = "tests" takeFileName file <.> ".ref" + print file + print new + contents <- readFile file + writeFile new (stripLinks contents) + + +stripLinks f = subRegex (mkRegexWithOpts "]*>" False False) f "" diff --git a/tests/html-tests/runtests.hs b/tests/html-tests/runtests.hs new file mode 100644 index 00000000..05bc28c5 --- /dev/null +++ b/tests/html-tests/runtests.hs @@ -0,0 +1,115 @@ +import System.Cmd +import System.Environment +import System.FilePath +import System.Exit +import System.Directory +import System.Process +import Data.List +import Control.Monad +import Text.Printf +import Text.Regex +import Distribution.Simple.Utils +import Distribution.Simple.Program +import Distribution.Verbosity +import Data.Maybe + + +haddockBase = ".." ".." +haddockPath = haddockBase "dist" "build" "haddock" "haddock" + + +main = do + test + putStrLn "All tests passed!" + + +test = do + x <- doesFileExist haddockPath + when (not x) $ die "you need to run 'cabal build' successfully first" + + contents <- getDirectoryContents "tests" + args <- getArgs + let (opts, spec) = span ("-" `isPrefixOf`) args + let mods = + case spec of + x:_ | x /= "all" -> [x ++ ".hs"] + _ -> filter ((==) ".hs" . takeExtension) contents + + let outdir = "output" + let mods' = map ("tests" ) mods + putStrLn "" + putStrLn "Haddock version: " + h1 <- runProcess haddockPath ["--version"] Nothing + (Just [("haddock_datadir", haddockBase)]) Nothing Nothing Nothing + waitForProcess h1 + putStrLn "" + putStrLn "GHC version: " + h2 <- runProcess haddockPath ["--ghc-version"] Nothing + (Just [("haddock_datadir", haddockBase)]) Nothing Nothing Nothing + waitForProcess h2 + putStrLn "" + + -- TODO: use Distribution.* to get the packages instead + libdir <- rawSystemStdout normal haddockPath ["--print-ghc-libdir"] + let librariesPath = "..""..""share""doc""ghc""html""libraries" + + let mkDep name version = + let path = init libdir librariesPath name ++ "-" ++ version + in "-i " ++ path ++ "," ++ path name ++ ".haddock" + + let base = mkDep "base" "4.3.0.0" + process = mkDep "process" "1.0.1.4" + ghcprim = mkDep "ghc-prim" "0.2.0.0" + + putStrLn "Running tests..." + handle <- runProcess haddockPath + (["-w", "-o", outdir, "-h", "--pretty-html", "--optghc=-fglasgow-exts" + , "--optghc=-w", base, process, ghcprim] ++ opts ++ mods') + Nothing (Just [("haddock_datadir", haddockBase)]) Nothing + Nothing Nothing + + code <- waitForProcess handle + when (code /= ExitSuccess) $ error "Haddock run failed! Exiting." + check mods (if not (null args) && args !! 0 == "all" then False else True) + + +check modules strict = do + forM_ modules $ \mod -> do + let outfile = "output" (dropExtension mod ++ ".html") + let reffile = "tests" dropExtension mod ++ ".html.ref" + b <- doesFileExist reffile + if b + then do + copyFile reffile ("output" takeFileName reffile) + out <- readFile outfile + ref <- readFile reffile + if not $ haddockEq out ref + then do + putStrLn $ "Output for " ++ mod ++ " has changed! Exiting with diff:" + let ref' = stripLinks ref + out' = stripLinks out + let reffile' = "output" takeFileName reffile ++ ".nolinks" + outfile' = "output" takeFileName outfile ++ ".nolinks" + writeFile reffile' ref' + writeFile outfile' out' + b <- programOnPath "colordiff" + if b + then system $ "colordiff " ++ reffile' ++ " " ++ outfile' + else system $ "diff " ++ reffile' ++ " " ++ outfile' + if strict then exitFailure else return () + else do + putStrLn $ "Pass: " ++ mod + else do + putStrLn $ "Pass: " ++ mod ++ " (no .ref file)" + + +haddockEq file1 file2 = stripLinks file1 == stripLinks file2 + + +stripLinks f = subRegex (mkRegexWithOpts "]*>" False False) f "" + + +programOnPath p = do + result <- findProgramLocation silent p + return (isJust result) + diff --git a/tests/html-tests/tests/A.hs b/tests/html-tests/tests/A.hs new file mode 100644 index 00000000..4a344a24 --- /dev/null +++ b/tests/html-tests/tests/A.hs @@ -0,0 +1,2 @@ +module A where +data A = A diff --git a/tests/html-tests/tests/A.html.ref b/tests/html-tests/tests/A.html.ref new file mode 100644 index 00000000..8f0e3765 --- /dev/null +++ b/tests/html-tests/tests/A.html.ref @@ -0,0 +1,68 @@ + +A

A

Documentation

data A

Constructors

A 
diff --git a/tests/html-tests/tests/B.hs b/tests/html-tests/tests/B.hs new file mode 100644 index 00000000..3a31507e --- /dev/null +++ b/tests/html-tests/tests/B.hs @@ -0,0 +1,2 @@ +module B ( module A ) where +import A diff --git a/tests/html-tests/tests/B.html.ref b/tests/html-tests/tests/B.html.ref new file mode 100644 index 00000000..abb08d45 --- /dev/null +++ b/tests/html-tests/tests/B.html.ref @@ -0,0 +1,51 @@ + +B

B

Documentation

module A

diff --git a/tests/html-tests/tests/Bug1.hs b/tests/html-tests/tests/Bug1.hs new file mode 100644 index 00000000..af1ed4d3 --- /dev/null +++ b/tests/html-tests/tests/Bug1.hs @@ -0,0 +1,6 @@ +module Bug1 where + +-- | We should have different anchors for constructors and types\/classes. This +-- hyperlink should point to the type constructor by default: 'T'. +data T = T + diff --git a/tests/html-tests/tests/Bug1.html.ref b/tests/html-tests/tests/Bug1.html.ref new file mode 100644 index 00000000..bc778d38 --- /dev/null +++ b/tests/html-tests/tests/Bug1.html.ref @@ -0,0 +1,89 @@ + +Bug1

Bug1

Synopsis

  • data T = T

Documentation

data T

We should have different anchors for constructors and types/classes. This + hyperlink should point to the type constructor by default: T. +

Constructors

T 
diff --git a/tests/html-tests/tests/Bug2.hs b/tests/html-tests/tests/Bug2.hs new file mode 100644 index 00000000..9121922e --- /dev/null +++ b/tests/html-tests/tests/Bug2.hs @@ -0,0 +1,4 @@ +module Bug2 ( x ) where +import B +x :: A +x = A diff --git a/tests/html-tests/tests/Bug2.html.ref b/tests/html-tests/tests/Bug2.html.ref new file mode 100644 index 00000000..ed81755d --- /dev/null +++ b/tests/html-tests/tests/Bug2.html.ref @@ -0,0 +1,53 @@ + +Bug2

Bug2

Documentation

x :: A

diff --git a/tests/html-tests/tests/Bug3.hs b/tests/html-tests/tests/Bug3.hs new file mode 100644 index 00000000..67e57892 --- /dev/null +++ b/tests/html-tests/tests/Bug3.hs @@ -0,0 +1,6 @@ +module Bug3 where + +-- | /multi-line +-- emphasis/ +foo :: Int +foo = undefined diff --git a/tests/html-tests/tests/Bug3.html.ref b/tests/html-tests/tests/Bug3.html.ref new file mode 100644 index 00000000..b231c443 --- /dev/null +++ b/tests/html-tests/tests/Bug3.html.ref @@ -0,0 +1,69 @@ + +Bug3

Bug3

Synopsis

Documentation

foo :: Int

/multi-line + emphasis/ +

diff --git a/tests/html-tests/tests/Bug4.hs b/tests/html-tests/tests/Bug4.hs new file mode 100644 index 00000000..425a77aa --- /dev/null +++ b/tests/html-tests/tests/Bug4.hs @@ -0,0 +1,5 @@ +module Bug4 where +-- | don't use apostrophe's in the wrong place's +foo :: Int +foo = undefined + diff --git a/tests/html-tests/tests/Bug4.html.ref b/tests/html-tests/tests/Bug4.html.ref new file mode 100644 index 00000000..776a0ab6 --- /dev/null +++ b/tests/html-tests/tests/Bug4.html.ref @@ -0,0 +1,68 @@ + +Bug4

Bug4

Synopsis

Documentation

foo :: Int

don't use apostrophe's in the wrong place's +

diff --git a/tests/html-tests/tests/Bug6.hs b/tests/html-tests/tests/Bug6.hs new file mode 100644 index 00000000..17411f31 --- /dev/null +++ b/tests/html-tests/tests/Bug6.hs @@ -0,0 +1,23 @@ +-- | Exporting records. +module Bug6( A(A), B(B), b, C(C,c1,c2), D(D,d1), E(E) ) where + +-- | +-- This record is exported without its field +data A = A { a :: Int } + +-- | +-- .. with its field, but the field is named separately in the export list +-- (the field isn't documented separately since it is already documented here) +data B = B { b :: Int } + +-- | +-- .. with fields names as subordinate names in the export +data C = C { c1 :: Int, c2 :: Int } + +-- | +-- .. with only some of the fields exported (we can't handle this one - +-- how do we render the declaration?) +data D = D { d1 :: Int, d2 :: Int } + +-- | a newtype with a field +newtype E = E { e :: Int } diff --git a/tests/html-tests/tests/Bug6.html.ref b/tests/html-tests/tests/Bug6.html.ref new file mode 100644 index 00000000..c6ee6452 --- /dev/null +++ b/tests/html-tests/tests/Bug6.html.ref @@ -0,0 +1,297 @@ + +Bug6

Bug6

Description

Exporting records. +

Synopsis

Documentation

data A

This record is exported without its field +

Constructors

A Int 

data B

.. with its field, but the field is named separately in the export list + (the field isn't documented separately since it is already documented here) +

Constructors

B 

Fields

b :: Int
 

data C

.. with fields names as subordinate names in the export +

Constructors

C 

Fields

c1 :: Int
 
c2 :: Int
 

data D

.. with only some of the fields exported (we can't handle this one - + how do we render the declaration?) +

Constructors

D Int Int 

newtype E

a newtype with a field +

Constructors

E Int 
diff --git a/tests/html-tests/tests/Bug7.hs b/tests/html-tests/tests/Bug7.hs new file mode 100644 index 00000000..8cf57914 --- /dev/null +++ b/tests/html-tests/tests/Bug7.hs @@ -0,0 +1,12 @@ +-- | This module caused a duplicate instance in the documentation for the Foo +-- type. +module Bug7 where + +-- | The Foo datatype +data Foo = Foo + +-- | The Bar class +class Bar x y + +-- | Just one instance +instance Bar Foo Foo diff --git a/tests/html-tests/tests/Bug7.html.ref b/tests/html-tests/tests/Bug7.html.ref new file mode 100644 index 00000000..eea2095d --- /dev/null +++ b/tests/html-tests/tests/Bug7.html.ref @@ -0,0 +1,153 @@ + +Bug7

Bug7

Description

This module caused a duplicate instance in the documentation for the Foo + type. +

Synopsis

Documentation

data Foo

The Foo datatype +

Constructors

Foo 

Instances

Bar Foo Foo

Just one instance +

class Bar x y

The Bar class +

Instances

Bar Foo Foo

Just one instance +

diff --git a/tests/html-tests/tests/Bug8.hs b/tests/html-tests/tests/Bug8.hs new file mode 100644 index 00000000..0f279c29 --- /dev/null +++ b/tests/html-tests/tests/Bug8.hs @@ -0,0 +1,17 @@ +{- Note that declarations without type signatures are not included in the + documentation. They could be, but that's a missing feature. -} + +module Bug8 where + +infix --> +infix ---> + +data Typ = Type (String,[Typ]) + | TFree (String, [String]) + +x --> y = Type("fun",[s,t]) +(--->) = flip $ foldr (-->) + +s = undefined +t = undefined +main = undefined diff --git a/tests/html-tests/tests/Bug8.html.ref b/tests/html-tests/tests/Bug8.html.ref new file mode 100644 index 00000000..e8ea727c --- /dev/null +++ b/tests/html-tests/tests/Bug8.html.ref @@ -0,0 +1,80 @@ + +Bug8

Bug8

Documentation

data Typ

Constructors

Type (String, [Typ]) 
TFree (String, [String]) 
diff --git a/tests/html-tests/tests/Bugs.hs b/tests/html-tests/tests/Bugs.hs new file mode 100644 index 00000000..8e1f0079 --- /dev/null +++ b/tests/html-tests/tests/Bugs.hs @@ -0,0 +1,3 @@ +module Bugs where + +data A a = A a (a -> Int) diff --git a/tests/html-tests/tests/Bugs.html.ref b/tests/html-tests/tests/Bugs.html.ref new file mode 100644 index 00000000..5828a6fa --- /dev/null +++ b/tests/html-tests/tests/Bugs.html.ref @@ -0,0 +1,69 @@ + +Bugs

Bugs

Documentation

data A a

Constructors

A a (a -> Int) 
diff --git a/tests/html-tests/tests/CrossPackageDocs.hs b/tests/html-tests/tests/CrossPackageDocs.hs new file mode 100644 index 00000000..de55060e --- /dev/null +++ b/tests/html-tests/tests/CrossPackageDocs.hs @@ -0,0 +1,3 @@ +module CrossPackageDocs (map, Monad(..), runInteractiveProcess) where + +import System.Process diff --git a/tests/html-tests/tests/CrossPackageDocs.html.ref b/tests/html-tests/tests/CrossPackageDocs.html.ref new file mode 100644 index 00000000..fd16c958 --- /dev/null +++ b/tests/html-tests/tests/CrossPackageDocs.html.ref @@ -0,0 +1,391 @@ + +CrossPackageDocs

CrossPackageDocs

Synopsis

Documentation

map :: (a -> b) -> [a] -> [b]

map f xs is the list obtained by applying f to each element + of xs, i.e., +

 map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
+ map f [x1, x2, ...] == [f x1, f x2, ...]
+

class Monad m where

The Monad class defines the basic operations over a monad, +a concept from a branch of mathematics known as category theory. +From the perspective of a Haskell programmer, however, it is best to +think of a monad as an abstract datatype of actions. +Haskell's do expressions provide a convenient syntax for writing +monadic expressions. +

Minimal complete definition: >>= and return. +

Instances of Monad should satisfy the following laws: +

 return a >>= k  ==  k a
+ m >>= return  ==  m
+ m >>= (\x -> k x >>= h)  ==  (m >>= k) >>= h
+

Instances of both Monad and Functor should additionally satisfy the law: +

 fmap f xs  ==  xs >>= return . f
+

The instances of Monad for lists, Data.Maybe.Maybe and System.IO.IO +defined in the Prelude satisfy these laws. +

Methods

(>>=) :: m a -> (a -> m b) -> m b

Sequentially compose two actions, passing any value produced + by the first as an argument to the second. +

(>>) :: m a -> m b -> m b

Sequentially compose two actions, discarding any value produced + by the first, like sequencing operators (such as the semicolon) + in imperative languages. +

return :: a -> m a

Inject a value into the monadic type. +

fail :: String -> m a

Fail with a message. This operation is not part of the + mathematical definition of a monad, but is invoked on pattern-match + failure in a do expression. +

Instances

Monad [] 
Monad IO 
Monad Q 
Monad Maybe 
Monad ((->) r) 
Monad (Either e) 

runInteractiveProcess

Arguments

:: FilePath

Filename of the executable +

-> [String]

Arguments to pass to the executable +

-> Maybe FilePath

Optional path to the working directory +

-> Maybe [(String, String)]

Optional environment (otherwise inherit) +

-> IO (Handle, Handle, Handle, ProcessHandle) 

Runs a raw command, and returns Handles that may be used to communicate + with the process via its stdin, stdout and stderr respectively. +

For example, to start a process and feed a string to its stdin: +

   (inp,out,err,pid) <- runInteractiveProcess "..."
+   forkIO (hPutStr inp str)
+

The Handles are initially in binary mode; if you need them to be + in text mode then use hSetBinaryMode. +

diff --git a/tests/html-tests/tests/Examples.hs b/tests/html-tests/tests/Examples.hs new file mode 100644 index 00000000..7b703428 --- /dev/null +++ b/tests/html-tests/tests/Examples.hs @@ -0,0 +1,34 @@ +module Examples where + +-- | Fibonacci number of given 'Integer'. +-- +-- Examples: +-- +-- >>> fib 5 +-- 5 +-- >>> fib 10 +-- 55 +-- +-- >>> fib 10 +-- 55 +-- +-- One more Example: +-- +-- >>> fib 5 +-- 5 +-- +-- One more Example: +-- +-- >>> fib 5 +-- 5 +-- +-- Example with an import: +-- +-- >>> import Data.Char +-- >>> isSpace 'a' +-- False +-- +fib :: Integer -> Integer +fib 0 = 0 +fib 1 = 1 +fib n = fib (n - 1) + fib (n - 2) diff --git a/tests/html-tests/tests/Examples.html.ref b/tests/html-tests/tests/Examples.html.ref new file mode 100644 index 00000000..49383b7a --- /dev/null +++ b/tests/html-tests/tests/Examples.html.ref @@ -0,0 +1,150 @@ + +Examples

Examples

Synopsis

Documentation

fib :: Integer -> Integer

Fibonacci number of given Integer. +

Examples: +

>>> fib 5
+5
+>>> fib 10
+55
+
>>> fib 10
+55
+

One more Example: +

>>> fib 5
+5
+

One more Example: +

>>> fib 5
+5
+

Example with an import: +

>>> import Data.Char
+>>> isSpace 'a'
+False
+
diff --git a/tests/html-tests/tests/FunArgs.hs b/tests/html-tests/tests/FunArgs.hs new file mode 100644 index 00000000..b34d84b7 --- /dev/null +++ b/tests/html-tests/tests/FunArgs.hs @@ -0,0 +1,16 @@ +module FunArgs where + +f :: forall a. Ord a + => Int -- ^ First argument + -> a -- ^ Second argument + -> Bool -- ^ Third argument + -> (a -> a) -- ^ Fourth argument + -> () -- ^ Result +f = undefined + + +g :: a -- ^ First argument + -> b -- ^ Second argument + -> c -- ^ Third argument + -> d -- ^ Result +g = undefined diff --git a/tests/html-tests/tests/FunArgs.html.ref b/tests/html-tests/tests/FunArgs.html.ref new file mode 100644 index 00000000..392ffca8 --- /dev/null +++ b/tests/html-tests/tests/FunArgs.html.ref @@ -0,0 +1,163 @@ + +FunArgs

FunArgs

Documentation

f

Arguments

:: forall a . Ord a 
=> Int

First argument +

-> a

Second argument +

-> Bool

Third argument +

-> (a -> a)

Fourth argument +

-> ()

Result +

g

Arguments

:: a

First argument +

-> b

Second argument +

-> c

Third argument +

-> d

Result +

diff --git a/tests/html-tests/tests/GADTRecords.hs b/tests/html-tests/tests/GADTRecords.hs new file mode 100644 index 00000000..c77810ad --- /dev/null +++ b/tests/html-tests/tests/GADTRecords.hs @@ -0,0 +1,12 @@ +{-# LANGUAGE GADTs #-} +module GADTRecords (H1(..)) where + +-- | h1 +data H1 a b where + C1 :: H1 a b + C2 :: Ord a => [a] -> H1 a a + C3 { field :: Int -- ^ hello docs + } :: H1 Int Int + C4 { field2 :: a -- ^ hello2 docs + } :: H1 Int a + diff --git a/tests/html-tests/tests/GADTRecords.html.ref b/tests/html-tests/tests/GADTRecords.html.ref new file mode 100644 index 00000000..fe80fae2 --- /dev/null +++ b/tests/html-tests/tests/GADTRecords.html.ref @@ -0,0 +1,197 @@ + +GADTRecords

GADTRecords

Synopsis

Documentation

data H1 a b where

h1 +

Constructors

C1 :: H1 a b 
C2 :: Ord a => [a] -> H1 a a 
C3 :: Int -> H1 Int Int 

Fields

field :: Int

hello docs +

C4 :: a -> H1 Int a 

Fields

field2 :: a

hello2 docs +

diff --git a/tests/html-tests/tests/Hash.hs b/tests/html-tests/tests/Hash.hs new file mode 100644 index 00000000..7d6506f9 --- /dev/null +++ b/tests/html-tests/tests/Hash.hs @@ -0,0 +1,51 @@ +{- | + Implementation of fixed-size hash tables, with a type + class for constructing hash values for structured types. +-} +module Hash ( + -- * The @HashTable@ type + HashTable, + + -- ** Operations on @HashTable@s + new, insert, lookup, + + -- * The @Hash@ class + Hash(..), + ) where + +import Array +import Prelude hiding (lookup) + +-- | A hash table with keys of type @key@ and values of type @val@. +-- The type @key@ should be an instance of 'Eq'. +data HashTable key val = HashTable Int (Array Int [(key,val)]) + +-- | Builds a new hash table with a given size +new :: (Eq key, Hash key) => Int -> IO (HashTable key val) +new = undefined + +-- | Inserts a new element into the hash table +insert :: (Eq key, Hash key) => key -> val -> IO () +insert = undefined + +-- | Looks up a key in the hash table, returns @'Just' val@ if the key +-- was found, or 'Nothing' otherwise. +lookup :: Hash key => key -> IO (Maybe val) +lookup = undefined + +-- | A class of types which can be hashed. +class Hash a where + -- | hashes the value of type @a@ into an 'Int' + hash :: a -> Int + +instance Hash Int where + hash = id + +instance Hash Float where + hash = trunc + +instance (Hash a, Hash b) => Hash (a,b) where + hash (a,b) = hash a `xor` hash b + +trunc = undefined +xor = undefined diff --git a/tests/html-tests/tests/Hash.html.ref b/tests/html-tests/tests/Hash.html.ref new file mode 100644 index 00000000..1bb64d42 --- /dev/null +++ b/tests/html-tests/tests/Hash.html.ref @@ -0,0 +1,284 @@ + +Hash

Hash

Description

Implementation of fixed-size hash tables, with a type + class for constructing hash values for structured types. +

Synopsis

The HashTable type +

data HashTable key val

A hash table with keys of type key and values of type val. + The type key should be an instance of Eq. +

Operations on HashTables +

new :: (Eq key, Hash key) => Int -> IO (HashTable key val)

Builds a new hash table with a given size +

insert :: (Eq key, Hash key) => key -> val -> IO ()

Inserts a new element into the hash table +

lookup :: Hash key => key -> IO (Maybe val)

Looks up a key in the hash table, returns Just val if the key + was found, or Nothing otherwise. +

The Hash class +

class Hash a where

A class of types which can be hashed. +

Methods

hash :: a -> Int

hashes the value of type a into an Int +

Instances

Hash Float 
Hash Int 
(Hash a, Hash b) => Hash (a, b) 
diff --git a/tests/html-tests/tests/Hidden.hs b/tests/html-tests/tests/Hidden.hs new file mode 100644 index 00000000..896da648 --- /dev/null +++ b/tests/html-tests/tests/Hidden.hs @@ -0,0 +1,6 @@ +{-# OPTIONS_HADDOCK hide #-} + +module Hidden where + +hidden :: Int -> Int +hidden a = a diff --git a/tests/html-tests/tests/NamedDoc.hs b/tests/html-tests/tests/NamedDoc.hs new file mode 100644 index 00000000..7c04ba72 --- /dev/null +++ b/tests/html-tests/tests/NamedDoc.hs @@ -0,0 +1,4 @@ +module NamedDoc where + +-- $foo bar + diff --git a/tests/html-tests/tests/NamedDoc.html.ref b/tests/html-tests/tests/NamedDoc.html.ref new file mode 100644 index 00000000..4c514487 --- /dev/null +++ b/tests/html-tests/tests/NamedDoc.html.ref @@ -0,0 +1,57 @@ + +NamedDoc

NamedDoc

Synopsis

    Documentation

    bar +

    diff --git a/tests/html-tests/tests/NoLayout.hs b/tests/html-tests/tests/NoLayout.hs new file mode 100644 index 00000000..19b38b1d --- /dev/null +++ b/tests/html-tests/tests/NoLayout.hs @@ -0,0 +1,12 @@ + +-- Haddock comments are parsed as separate declarations so we +-- need to insert a ';' when using them with explicit layout. +-- This should probably be changed. + +module NoLayout where { + -- | the function 'g' + ; + g :: Int; + g = undefined + } + diff --git a/tests/html-tests/tests/NoLayout.html.ref b/tests/html-tests/tests/NoLayout.html.ref new file mode 100644 index 00000000..cb073bf6 --- /dev/null +++ b/tests/html-tests/tests/NoLayout.html.ref @@ -0,0 +1,71 @@ + +NoLayout

    NoLayout

    Synopsis

    Documentation

    g :: Int

    the function g +

    diff --git a/tests/html-tests/tests/NonGreedy.hs b/tests/html-tests/tests/NonGreedy.hs new file mode 100644 index 00000000..f51b55f5 --- /dev/null +++ b/tests/html-tests/tests/NonGreedy.hs @@ -0,0 +1,5 @@ +module NonGreedy where + +-- | +f :: a +f = undefined diff --git a/tests/html-tests/tests/NonGreedy.html.ref b/tests/html-tests/tests/NonGreedy.html.ref new file mode 100644 index 00000000..9e39b7c3 --- /dev/null +++ b/tests/html-tests/tests/NonGreedy.html.ref @@ -0,0 +1,68 @@ + +NonGreedy

    NonGreedy

    Synopsis

    • f :: a

    Documentation

    f :: a

    url1 url2 +

    diff --git a/tests/html-tests/tests/QuasiExpr.hs b/tests/html-tests/tests/QuasiExpr.hs new file mode 100644 index 00000000..970759ba --- /dev/null +++ b/tests/html-tests/tests/QuasiExpr.hs @@ -0,0 +1,34 @@ +{-# LANGUAGE TemplateHaskell #-} + +-- Used by QuasiQuote. Example taken from the GHC documentation. +module QuasiExpr where + +import Language.Haskell.TH +import Language.Haskell.TH.Quote + +data Expr = IntExpr Integer + | AntiIntExpr String + | BinopExpr BinOp Expr Expr + | AntiExpr String + deriving Show + +data BinOp = AddOp + | SubOp + | MulOp + | DivOp + deriving Show + +eval :: Expr -> Integer +eval (IntExpr n) = n +eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y) + where + opToFun AddOp = (+) + opToFun SubOp = (-) + opToFun MulOp = (*) + opToFun DivOp = div + +expr = QuasiQuoter parseExprExp undefined undefined undefined + +-- cheating... +parseExprExp :: String -> Q Exp +parseExprExp _ = [| BinopExpr AddOp (IntExpr 1) (IntExpr 2) |] diff --git a/tests/html-tests/tests/QuasiExpr.html.ref b/tests/html-tests/tests/QuasiExpr.html.ref new file mode 100644 index 00000000..321631e4 --- /dev/null +++ b/tests/html-tests/tests/QuasiExpr.html.ref @@ -0,0 +1,191 @@ + +QuasiExpr

    QuasiExpr

    Documentation

    data Expr

    Constructors

    IntExpr Integer 
    AntiIntExpr String 
    BinopExpr BinOp Expr Expr 
    AntiExpr String 

    Instances

    data BinOp

    Constructors

    AddOp 
    SubOp 
    MulOp 
    DivOp 

    Instances

    eval :: Expr -> Integer

    parseExprExp :: String -> Q Exp

    diff --git a/tests/html-tests/tests/QuasiQuote.hs b/tests/html-tests/tests/QuasiQuote.hs new file mode 100644 index 00000000..06762cf9 --- /dev/null +++ b/tests/html-tests/tests/QuasiQuote.hs @@ -0,0 +1,9 @@ +{-# LANGUAGE TemplateHaskell, QuasiQuotes #-} + +-- example taken from the GHC documentation +module QuasiQuote where + +import QuasiExpr + +val :: Integer +val = eval [expr|1 + 2|] diff --git a/tests/html-tests/tests/QuasiQuote.html.ref b/tests/html-tests/tests/QuasiQuote.html.ref new file mode 100644 index 00000000..e1159268 --- /dev/null +++ b/tests/html-tests/tests/QuasiQuote.html.ref @@ -0,0 +1,53 @@ + +QuasiQuote

    QuasiQuote

    Documentation

    val :: Integer

    diff --git a/tests/html-tests/tests/TH.hs b/tests/html-tests/tests/TH.hs new file mode 100644 index 00000000..f8178bcb --- /dev/null +++ b/tests/html-tests/tests/TH.hs @@ -0,0 +1,8 @@ +{-# LANGUAGE TemplateHaskell #-} + +module TH where + +import Language.Haskell.TH + +decl :: Q [Dec] +decl = [d| f x = x|] diff --git a/tests/html-tests/tests/TH.html.ref b/tests/html-tests/tests/TH.html.ref new file mode 100644 index 00000000..be948582 --- /dev/null +++ b/tests/html-tests/tests/TH.html.ref @@ -0,0 +1,52 @@ + +TH

    TH

    Documentation

    decl :: Q [Dec]

    diff --git a/tests/html-tests/tests/TH2.hs b/tests/html-tests/tests/TH2.hs new file mode 100644 index 00000000..f8f27710 --- /dev/null +++ b/tests/html-tests/tests/TH2.hs @@ -0,0 +1,8 @@ +{-# LANGUAGE TemplateHaskell #-} + +module TH2 where + +import TH + +-- we can't add a type sig here, so we get no doc +$( decl ) diff --git a/tests/html-tests/tests/TH2.html.ref b/tests/html-tests/tests/TH2.html.ref new file mode 100644 index 00000000..950a391b --- /dev/null +++ b/tests/html-tests/tests/TH2.html.ref @@ -0,0 +1,44 @@ + +TH2

    TH2

    diff --git a/tests/html-tests/tests/Test.hs b/tests/html-tests/tests/Test.hs new file mode 100644 index 00000000..d7a0a716 --- /dev/null +++ b/tests/html-tests/tests/Test.hs @@ -0,0 +1,414 @@ +----------------------------------------------------------------------------- +-- | +-- 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 +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: . +-} + +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 + + +-- 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/tests/html-tests/tests/Test.html.ref b/tests/html-tests/tests/Test.html.ref new file mode 100644 index 00000000..2acc5ec8 --- /dev/null +++ b/tests/html-tests/tests/Test.html.ref @@ -0,0 +1,1968 @@ + +Test
    Portabilityportable
    Stabilityprovisional
    Maintainerlibraries@haskell.org

    Test

    Description

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

    Synopsis

    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 :: Int

    This comment applies to both r and s +

    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 :: Int
     
    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

    class E a

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

    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\'' +

    diff --git a/tests/html-tests/tests/Ticket112.hs b/tests/html-tests/tests/Ticket112.hs new file mode 100644 index 00000000..c9cd5117 --- /dev/null +++ b/tests/html-tests/tests/Ticket112.hs @@ -0,0 +1,9 @@ +{-# LANGUAGE MagicHash #-} + +module Ticket112 where + +import GHC.Prim + +-- | ...given a raw 'Addr#' to the string, and the length of the string. +f :: a +f = undefined diff --git a/tests/html-tests/tests/Ticket112.html.ref b/tests/html-tests/tests/Ticket112.html.ref new file mode 100644 index 00000000..f29b507a --- /dev/null +++ b/tests/html-tests/tests/Ticket112.html.ref @@ -0,0 +1,69 @@ + +Ticket112

    Ticket112

    Synopsis

    • f :: a

    Documentation

    f :: a

    ...given a raw Addr# to the string, and the length of the string. +

    diff --git a/tests/html-tests/tests/Ticket61.hs b/tests/html-tests/tests/Ticket61.hs new file mode 100644 index 00000000..26ca287f --- /dev/null +++ b/tests/html-tests/tests/Ticket61.hs @@ -0,0 +1,3 @@ +module Ticket61 (module Ticket61_Hidden) where + +import Ticket61_Hidden diff --git a/tests/html-tests/tests/Ticket61.html.ref b/tests/html-tests/tests/Ticket61.html.ref new file mode 100644 index 00000000..453cabad --- /dev/null +++ b/tests/html-tests/tests/Ticket61.html.ref @@ -0,0 +1,69 @@ + +Ticket61

    Ticket61

    Documentation

    class C a where

    Methods

    f :: a

    A comment about f +

    diff --git a/tests/html-tests/tests/Ticket61_Hidden.hs b/tests/html-tests/tests/Ticket61_Hidden.hs new file mode 100644 index 00000000..583c10cd --- /dev/null +++ b/tests/html-tests/tests/Ticket61_Hidden.hs @@ -0,0 +1,7 @@ +{-# OPTIONS_HADDOCK hide #-} + +module Ticket61_Hidden where + +class C a where + -- | A comment about f + f :: a diff --git a/tests/html-tests/tests/Ticket75.hs b/tests/html-tests/tests/Ticket75.hs new file mode 100644 index 00000000..94a2f115 --- /dev/null +++ b/tests/html-tests/tests/Ticket75.hs @@ -0,0 +1,7 @@ +module Ticket75 where + +data a :- b = Q + +-- | A reference to ':-' +f :: Int +f = undefined diff --git a/tests/html-tests/tests/Ticket75.html.ref b/tests/html-tests/tests/Ticket75.html.ref new file mode 100644 index 00000000..dcadf429 --- /dev/null +++ b/tests/html-tests/tests/Ticket75.html.ref @@ -0,0 +1,99 @@ + +Ticket75

    Ticket75

    Synopsis

    Documentation

    data a :- b

    Constructors

    Q 

    f :: Int

    A reference to :- +

    diff --git a/tests/html-tests/tests/TypeFamilies.hs b/tests/html-tests/tests/TypeFamilies.hs new file mode 100644 index 00000000..561f95fd --- /dev/null +++ b/tests/html-tests/tests/TypeFamilies.hs @@ -0,0 +1,28 @@ +{-# LANGUAGE TypeFamilies #-} + +module TypeFamilies where + +-- | Type family G +type family G a :: * + +-- | A class with an associated type +class A a where + -- | An associated type + data B a :: * -> * + -- | A method + f :: B a Int + +-- | Doc for family +type family F a + + +-- | Doc for G Int +type instance G Int = Bool +type instance G Float = Int + + +instance A Int where + data B Int x = Con x + f = Con 3 + +g = Con 5 diff --git a/tests/html-tests/tests/TypeFamilies.html.ref b/tests/html-tests/tests/TypeFamilies.html.ref new file mode 100644 index 00000000..02ad9920 --- /dev/null +++ b/tests/html-tests/tests/TypeFamilies.html.ref @@ -0,0 +1,168 @@ + +TypeFamilies

    TypeFamilies

    Synopsis

    • type family G a :: *
    • class A a where
      • data B a :: * -> *
      • f :: B a Int
    • type family F a

    Documentation

    type family G a :: *

    Type family G +

    class A a where

    A class with an associated type +

    Associated Types

    data B a :: * -> *

    An associated type +

    Methods

    f :: B a Int

    A method +

    Instances

    A Int 

    type family F a

    Doc for family +

    diff --git a/tests/html-tests/tests/TypeOperators.hs b/tests/html-tests/tests/TypeOperators.hs new file mode 100644 index 00000000..aa0fbe8c --- /dev/null +++ b/tests/html-tests/tests/TypeOperators.hs @@ -0,0 +1,22 @@ +module TypeOperators ( + -- * stuff + (:-:), + (:+:), + Op, + O(..), + biO, + Flip(..) +) where + +data a :-: b + +data (a :+: b) c + +data a `Op` b + +newtype (g `O` f) a = O { unO :: g (f a) } + +biO :: (g `O` f) a +biO = undefined + +newtype Flip (~>) b a = Flip { unFlip :: a ~> b } diff --git a/tests/html-tests/tests/TypeOperators.html.ref b/tests/html-tests/tests/TypeOperators.html.ref new file mode 100644 index 00000000..445af672 --- /dev/null +++ b/tests/html-tests/tests/TypeOperators.html.ref @@ -0,0 +1,215 @@ + +TypeOperators

    TypeOperators

    Contents

    Synopsis

    stuff +

    data a :-: b

    data (a :+: b) c

    data Op a b

    newtype O g f a

    Constructors

    O 

    Fields

    unO :: g (f a)
     

    biO :: (g `O` f) a

    newtype Flip (~>) b a

    Constructors

    Flip 

    Fields

    unFlip :: a ~> b
     
    diff --git a/tests/html-tests/tests/Visible.hs b/tests/html-tests/tests/Visible.hs new file mode 100644 index 00000000..cad71931 --- /dev/null +++ b/tests/html-tests/tests/Visible.hs @@ -0,0 +1,3 @@ +module Visible where +visible :: Int -> Int +visible a = a diff --git a/tests/html-tests/tests/Visible.html.ref b/tests/html-tests/tests/Visible.html.ref new file mode 100644 index 00000000..3dc3418f --- /dev/null +++ b/tests/html-tests/tests/Visible.html.ref @@ -0,0 +1,54 @@ + +Visible

    Visible

    Documentation

    visible :: Int -> Int

    -- cgit v1.2.3