aboutsummaryrefslogtreecommitdiff
path: root/haddock-library
diff options
context:
space:
mode:
authorAlec Theriault <alec.theriault@gmail.com>2018-03-26 23:35:59 -0700
committerAlexander Biehl <alexbiehl@gmail.com>2018-03-27 08:35:59 +0200
commit978dbc859df09eb991d9ccc0911276cc9655b783 (patch)
tree8082d90d0c73db65292ba844e19ae92c3e9ad1a6 /haddock-library
parentd270aeee23427c8cfe582549ead8f495704603f6 (diff)
@since includes package name (#749)
* Metadoc stores a package name This means that '@since' annotations can be package aware. * Get the package name the right way This should extract the package name for `@since` annotations the right way. I had to move `modulePackageInfo` around to do this and, in the process, I took the liberty to update it. Since it appears that finding the package name is something that can fail, I added a warning for this case. * Silence warnings * Hide package for local 'since' annotations As discussed, this is still the usual case (and we should avoid being noisy for it). Although this commit is large, it is basically only about threading a 'Maybe Package' from 'Haddock.render' all the way to 'Haddock.Backends.Xhtml.DocMarkup.renderMeta'. * Bump binary interface version * Add a '--since-qual' option This controls when to qualify since annotations with the package they come from. The default is always, but I've left an 'external' variant where only those annotations coming from outside of the current package are qualified. * Make ParserSpec work * Make Fixtures work * Use package name even if package version is not available The @since stuff needs only the package name passed in, so it makes sense to not be forced to pass in a version too.
Diffstat (limited to 'haddock-library')
-rw-r--r--haddock-library/fixtures/Fixtures.hs2
-rw-r--r--haddock-library/src/Documentation/Haddock/Doc.hs8
-rw-r--r--haddock-library/src/Documentation/Haddock/Parser.hs9
-rw-r--r--haddock-library/src/Documentation/Haddock/Types.hs5
-rw-r--r--haddock-library/test/Documentation/Haddock/ParserSpec.hs17
5 files changed, 27 insertions, 14 deletions
diff --git a/haddock-library/fixtures/Fixtures.hs b/haddock-library/fixtures/Fixtures.hs
index 282fd10d..a4e4321f 100644
--- a/haddock-library/fixtures/Fixtures.hs
+++ b/haddock-library/fixtures/Fixtures.hs
@@ -102,7 +102,7 @@ acceptFixtures = traverse_ $ \(Fixture i o) -> do
writeFile o actual
parseString :: String -> Doc String
-parseString = Parse.toRegular . _doc . Parse.parseParas
+parseString = Parse.toRegular . _doc . Parse.parseParas Nothing
data Cmd = CmdRun | CmdAccept | CmdList
diff --git a/haddock-library/src/Documentation/Haddock/Doc.hs b/haddock-library/src/Documentation/Haddock/Doc.hs
index 66bd1c97..297d30d6 100644
--- a/haddock-library/src/Documentation/Haddock/Doc.hs
+++ b/haddock-library/src/Documentation/Haddock/Doc.hs
@@ -27,16 +27,16 @@ metaDocAppend (MetaDoc { _meta = m, _doc = d })
(MetaDoc { _meta = m', _doc = d' }) =
MetaDoc { _meta = m' `metaAppend` m, _doc = d `docAppend` d' }
--- | This is not a monoidal append, it uses '<|>' for the '_version'.
+-- | This is not a monoidal append, it uses '<|>' for the '_version' and
+-- '_package'.
metaAppend :: Meta -> Meta -> Meta
-metaAppend (Meta { _version = v }) (Meta { _version = v' }) =
- Meta { _version = v <|> v' }
+metaAppend (Meta v1 p1) (Meta v2 p2) = Meta (v1 <|> v2) (p1 <|> p2)
emptyMetaDoc :: MetaDoc mod id
emptyMetaDoc = MetaDoc { _meta = emptyMeta, _doc = DocEmpty }
emptyMeta :: Meta
-emptyMeta = Meta { _version = empty }
+emptyMeta = Meta empty empty
docAppend :: DocH mod id -> DocH mod id -> DocH mod id
docAppend (DocDefList ds1) (DocDefList ds2) = DocDefList (ds1++ds2)
diff --git a/haddock-library/src/Documentation/Haddock/Parser.hs b/haddock-library/src/Documentation/Haddock/Parser.hs
index 6cbc3922..4921b3a7 100644
--- a/haddock-library/src/Documentation/Haddock/Parser.hs
+++ b/haddock-library/src/Documentation/Haddock/Parser.hs
@@ -116,10 +116,13 @@ parse p = either err id . parseOnly (p <* endOfInput)
-- | Main entry point to the parser. Appends the newline character
-- to the input string.
-parseParas :: String -- ^ String to parse
+parseParas :: Maybe Package
+ -> String -- ^ String to parse
-> MetaDoc mod Identifier
-parseParas input = case parseParasState input of
- (state, a) -> MetaDoc { _meta = Meta { _version = parserStateSince state }
+parseParas pkg input = case parseParasState input of
+ (state, a) -> MetaDoc { _meta = Meta { _version = parserStateSince state
+ , _package = pkg
+ }
, _doc = a
}
diff --git a/haddock-library/src/Documentation/Haddock/Types.hs b/haddock-library/src/Documentation/Haddock/Types.hs
index 209f26e8..005ec186 100644
--- a/haddock-library/src/Documentation/Haddock/Types.hs
+++ b/haddock-library/src/Documentation/Haddock/Types.hs
@@ -34,7 +34,9 @@ import Data.Bitraversable
-- meta-data to comments. We make a structure for this ahead of time
-- so we don't have to gut half the core each time we want to add such
-- info.
-newtype Meta = Meta { _version :: Maybe Version } deriving (Eq, Show)
+data Meta = Meta { _version :: Maybe Version
+ , _package :: Maybe Package
+ } deriving (Eq, Show)
data MetaDoc mod id =
MetaDoc { _meta :: Meta
@@ -61,6 +63,7 @@ overDocF :: Functor f => (DocH a b -> f (DocH c d)) -> MetaDoc a b -> f (MetaDoc
overDocF f d = (\x -> d { _doc = x }) <$> f (_doc d)
type Version = [Int]
+type Package = String
data Hyperlink = Hyperlink
{ hyperlinkUrl :: String
diff --git a/haddock-library/test/Documentation/Haddock/ParserSpec.hs b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
index c605e2c2..86ed3b35 100644
--- a/haddock-library/test/Documentation/Haddock/ParserSpec.hs
+++ b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
@@ -24,8 +24,15 @@ instance IsString (Doc String) where
instance IsString a => IsString (Maybe a) where
fromString = Just . fromString
+emptyMeta :: Meta
+emptyMeta =
+ Meta {
+ _version = Nothing
+ , _package = Nothing
+ }
+
parseParas :: String -> MetaDoc () String
-parseParas = overDoc Parse.toRegular . Parse.parseParas
+parseParas = overDoc Parse.toRegular . Parse.parseParas Nothing
parseString :: String -> Doc String
parseString = Parse.toRegular . Parse.parseString
@@ -375,17 +382,17 @@ spec = do
context "when parsing @since" $ do
it "adds specified version to the result" $ do
parseParas "@since 0.5.0" `shouldBe`
- MetaDoc { _meta = Meta { _version = Just [0,5,0] }
+ MetaDoc { _meta = emptyMeta { _version = Just [0,5,0] }
, _doc = DocEmpty }
it "ignores trailing whitespace" $ do
parseParas "@since 0.5.0 \t " `shouldBe`
- MetaDoc { _meta = Meta { _version = Just [0,5,0] }
+ MetaDoc { _meta = emptyMeta { _version = Just [0,5,0] }
, _doc = DocEmpty }
it "does not allow trailing input" $ do
parseParas "@since 0.5.0 foo" `shouldBe`
- MetaDoc { _meta = Meta { _version = Nothing }
+ MetaDoc { _meta = emptyMeta { _version = Nothing }
, _doc = DocParagraph "@since 0.5.0 foo" }
@@ -395,7 +402,7 @@ spec = do
"@since 0.5.0"
, "@since 0.6.0"
, "@since 0.7.0"
- ] `shouldBe` MetaDoc { _meta = Meta { _version = Just [0,7,0] }
+ ] `shouldBe` MetaDoc { _meta = emptyMeta { _version = Just [0,7,0] }
, _doc = DocEmpty }