diff options
19 files changed, 120 insertions, 95 deletions
diff --git a/compiler/hsSyn/HsDoc.hs b/compiler/hsSyn/HsDoc.hs index 1f3adafec1..2cb28540f9 100644 --- a/compiler/hsSyn/HsDoc.hs +++ b/compiler/hsSyn/HsDoc.hs @@ -20,7 +20,7 @@ newtype HsDocString = HsDocString FastString type LHsDocString = Located HsDocString instance Outputable HsDocString where - ppr _ = text "<document comment>" + ppr (HsDocString fs) = ftext fs ppr_mbDoc :: Maybe LHsDocString -> SDoc ppr_mbDoc (Just doc) = ppr doc diff --git a/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr b/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr index 37a2565a4e..097b6ef1dd 100644 --- a/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr +++ b/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr @@ -17,50 +17,74 @@ hidden a = a [3 of 3] Compiling Test ( Test.hs, Test.o ) ==================== Parser ==================== -<document comment> + + 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'. + 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: 2>, R(..), R1(..), + test that we can export record selectors on their own:, p, q, u, + <IEGroup: 1>, C(a, b), D(..), E, F(..), + Test that we can export a class method on its own:, 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>, + <IEDocNamed: aux11>, <IEDocNamed: 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)., <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' + nested-style doc comments , <IEGroup: 1>, Ex(..), <IEGroup: 1>, k, + l, m, o, <IEGroup: 1>, <IEGroup: 2>, + + > a literal line + + $ a non /literal/ line $ +, 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) + = This comment describes the 'A' constructor A Int (Maybe Float) | + This comment describes the 'B' constructor 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 +data T5 a b = documents 'A3' A3 a | documents 'B3' B3 b <document comment> data T6 - = <document comment> A4 | - <document comment> B4 | - <document comment> C4 + = This is the doc for 'A4' A4 | + This is the doc for 'B4' B4 | + This is the doc for 'C4' 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>} +newtype N3 a b = N3 {n3 :: a b this is the 'n3' field } <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} +newtype N5 a b + = N5 {n5 :: a b no docs on the datatype or the constructor} +newtype N6 a b = docs on the constructor only N6 {n6 :: a b} <document comment> -newtype N7 a b = <document comment> N7 {n7 :: a b} +newtype N7 a b = The 'N7' constructor N7 {n7 :: a b} class D a => C a where a :: IO a b :: [a] @@ -83,22 +107,22 @@ 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> + = 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, + r :: Int This comment applies to both 'r' and 's', + s :: Int This comment applies to both 'r' and 's'} | + This is the 'C2' record constructor, also with some fields: 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>} + = This is the 'C3' record constructor + C3 {s1 :: Int The 's1' record selector, + s2 :: Int The 's2' record selector, + s3 :: Int The 's3' record selector} <document comment> <document comment> <document comment> @@ -129,19 +153,26 @@ data Ex a 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 + 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 +l :: (Int, Int, Float) takes a triple -> Int returns an 'Int' +<document comment> +m :: + R -> N1 () one of the arguments -> IO Int and the return value +<document comment> +newn :: + R one of the arguments, an 'R' + -> N1 () one of the arguments -> IO Int newn = undefined <document comment> foreign import ccall unsafe "static header.h o" o - :: Float <document comment> -> IO Float <document comment> + :: Float The input float -> IO Float The output float <document comment> newp :: Int newp = undefined diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr index f71f89a89e..a70f624278 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr @@ -1,6 +1,6 @@ ==================== Parser ==================== -<document comment> + a header module HeaderTest where <document comment> x = 0 diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr index 356d5b73bf..3bfc17d811 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr @@ -1,6 +1,6 @@ ==================== Parser ==================== -<document comment> + a header module HeaderTest where <document comment> x = 0 diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr index 1f436a7bec..48dd0870c9 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr @@ -1,6 +1,6 @@ ==================== Parser ==================== -<document comment> +Module description module A where diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr index 1f436a7bec..2aa5245f50 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr @@ -1,6 +1,6 @@ ==================== Parser ==================== -<document comment> + module header bla bla module A where diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr index 68e7b4f225..ca316bc8b8 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr @@ -1,7 +1,7 @@ ==================== Parser ==================== module A ( - <document comment>, <document comment> + bla bla, blabla ) where diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr index 20c628006d..2aaa3eba98 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr @@ -1,7 +1,7 @@ ==================== Parser ==================== module A ( - <document comment>, <document comment>, x, <IEGroup: 2>, <document comment> + bla bla, blabla , x, <IEGroup: 2>, qweljqwelkqjwelqjkq ) where x = True diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr index edf523dfa2..162c403b84 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr @@ -1,8 +1,8 @@ ==================== Parser ==================== module A ( - <document comment>, <document comment>, x, <IEGroup: 2>, <document comment>, y, - <document comment>, z, <IEGroup: 1> + bla bla, blabla , x, <IEGroup: 2>, qweljqwelkqjwelqjkq, y, + dkashdakj, z, <IEGroup: 1> ) where x = True y = False diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr index 2c4f5bc952..6d803bb440 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr @@ -1,10 +1,7 @@ -
-==================== Parser ====================
-module ShouldCompile where
-test ::
- Eq a =>
- [a] <document comment>
- -> [a] <document comment> -> [a] <document comment>
-test xs ys = xs
-
-
+ +==================== Parser ==================== +module ShouldCompile where +test :: Eq a => [a] doc1 -> [a] doc2 -> [a] doc3 +test xs ys = xs + + diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr index f0d269d0b1..b3caa71b9e 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr @@ -1,7 +1,7 @@ ==================== Parser ==================== module ShouldCompile where -test2 :: a <document comment> -> b <document comment> -> a <document comment> +test2 :: a doc1 -> b doc2 -> a doc 3 test2 x y = x diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr index 792da55155..472ec1a1eb 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr @@ -1,7 +1,7 @@ ==================== Parser ==================== module ShouldCompile where -test2 :: a <document comment> -> a +test2 :: a doc1 -> a test2 x = x diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr index e352980fd4..3e3cb12d10 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr @@ -1,10 +1,7 @@ -
-==================== Parser ====================
-module ShouldCompile where
-test ::
- Eq a =>
- [a] <document comment>
- -> forall b. [b] <document comment> -> [a] <document comment>
-test xs ys = xs
-
-
+ +==================== Parser ==================== +module ShouldCompile where +test :: Eq a => [a] doc1 -> forall b. [b] doc2 -> [a] doc3 +test xs ys = xs + + diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr index 67bf6528c0..10e88d2bfc 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr @@ -1,11 +1,10 @@ -
-==================== Parser ====================
-module ShouldCompile where
-test ::
- [a] <document comment>
- -> forall b. Ord b =>
- [b] <document comment>
- -> forall c. Num c => [c] <document comment> -> [a]
-test xs ys zs = xs
-
-
+ +==================== Parser ==================== +module ShouldCompile where +test :: + [a] doc1 + -> forall b. Ord b => + [b] doc2 -> forall c. Num c => [c] doc3 -> [a] +test xs ys zs = xs + + diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr index 6d9a8b2181..fa0d7019c0 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr @@ -2,8 +2,7 @@ ==================== Parser ==================== module ShouldCompile where data (<-->) a b = Mk a b -test :: - [a] <document comment> -> (a <--> (b -> [a])) <document comment> +test :: [a] doc1 -> (a <--> (b -> [a])) blabla test xs ys = xs diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr index aa48d998ef..820ffa6708 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr @@ -1,6 +1,7 @@ ==================== Parser ==================== module ShouldCompile where -data A = <document comment> A | B | C | D +data A + = A comment that documents the first constructor A | B | C | D diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr index c879d2244b..b0ef139199 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr @@ -1,6 +1,7 @@ ==================== Parser ==================== module ShouldCompile where -data A = <document comment> A | <document comment> B | <document comment> C | D +data A + = comment for A A | comment for B B | comment for C C | D diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr index 75ac2945b8..1d033cd6d7 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr @@ -1,9 +1,9 @@ -
-==================== Parser ====================
-module ShouldCompile where
-data A
- = A |
- <document comment> forall a. B a a |
- <document comment> forall a. Num a => C a
-
-
+ +==================== Parser ==================== +module ShouldCompile where +data A + = A | + comment for B forall a. B a a | + comment for C forall a. Num a => C a + + diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr index 2b0e4d24af..5cf2d9b034 100644 --- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr +++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr @@ -2,9 +2,9 @@ ==================== Parser ==================== module ShouldCompile where data R a - = R {field1 :: a, - field2 :: a <document comment>, - field3 :: a <document comment>, - field4 :: a <document comment>} + = R {field1 :: a, + field2 :: a comment for field2, + field3 :: a comment for field3, + field4 :: a comment for field4 } |