Can I link to a module which my package depends on but which is not imported?

[tomjaguarpaw]

Can I link to a module which my package depends on but which is not imported? This issue suggests not #388. But if that is really the case then what is the rationale? I can always get the behaviour I want at the cost of a redundant import. Couldn't Haddock just simulate that?

[hvr]

This is one of the things that the "hi haddock" GSOC project should be able to resolve, as its goal is to move the haddock docstring parsing into GHC so that GHC can already pre-resolve the haskell references (including module name references) via the renamer phase.

[alexbiehl]

Tom, I think this should be somewhat possible today. The following is my reasoning about why it should work:

We have a production for DocModule:

haddock/haddock-library/src/Documentation/Haddock/Parser.hs

Lines 145 to 154 in 256b908

	parseStringBS :: BS.ByteString -> DocH mod Identifier
	parseStringBS = snd . parse p
	where
	p :: Parser (DocH mod Identifier)
	p = docConcat <$> many (monospace <|> anchor <|> identifier <|> moduleName
	<|> picture <|> mathDisplay <|> mathInline
	<|> markdownImage
	<|> hyperlink <|> bold
	<|> emphasis <|> encodedChar <|> string'
	<|> skipSpecialChar)

haddock/haddock-library/src/Documentation/Haddock/Types.hs

Line 110 in 256b908

| DocModule String

Note that this is a plain String and not GHC identifier. So this won't be renamed or resolved by GHC or Haddock in the usual way identifiers are. Instead take a look at

haddock/haddock-api/src/Haddock/Backends/Xhtml/DocMarkup.hs

Lines 47 to 53 in 256b908

	markupModule = \m -> let (mdl,ref) = break (=='#') m
	-- Accomodate for old style
	-- foo\#bar anchors
	mdl' = case reverse mdl of
	'\\':_ -> init mdl
	_ -> mdl
	in ppModuleRef (mkModuleName mdl') ref,

where

haddock/haddock-api/src/Haddock/Backends/Xhtml/Names.hs

Lines 173 to 175 in 4abf7d4

	ppModuleRef :: ModuleName -> String -> Html
	ppModuleRef mdl ref = anchor ! [href (moduleHtmlFile' mdl ++ ref)]
	<< toHtml (moduleNameString mdl)

where

haddock/haddock-api/src/Haddock/Utils.hs

Lines 251 to 255 in 4abf7d4

	moduleHtmlFile' :: ModuleName -> FilePath
	moduleHtmlFile' mdl =
	case Map.lookup mdl html_xrefs' of
	Nothing -> baseName mdl ++ ".html"
	Just fp0 -> HtmlPath.joinPath [fp0, baseName mdl ++ ".html"]

So resolving a DocModule will lookup the FilePath from html_xrefs'! Let's see where html_xrefs ' get populated:

haddock/haddock-api/src/Haddock.hs

Lines 594 to 601 in 978dbc8

	updateHTMLXRefs :: [(DocPaths, InterfaceFile)] -> IO ()
	updateHTMLXRefs packages = do
	writeIORef html_xrefs_ref (Map.fromList mapping)
	writeIORef html_xrefs_ref' (Map.fromList mapping')
	where
	mapping = [ (instMod iface, html) | ((html, _), ifaces) <- packages
	, iface <- ifInstalledIfaces ifaces ]
	mapping' = [ (moduleName m, html) | (m, html) <- mapping ]

For some reason we are using a global mutable variable to pass the cross references to the XHTML backend. But that is not important now. We can see that we include every InstalledInterface (~= Module) we passed to haddock on invocation in the xrefs mapping.

That would mean, as long as your module is somewhere in your dependency tree and you are passing that packages .haddock file to haddock it should get linked. Thus linking a module has nothing to do with importing stuff.

[alexbiehl]

(That is to say, we should investigate why it wouldn't work for your case)

[tomjaguarpaw]

You mean what am I asking for is already implemented? Which Haddock version? I am using Haddock version 2.17.2 which came with Debian's ghc package (version 8.0.1).

[tomjaguarpaw]

I am also using:
cabal-install version 2.2.0.0
compiled using version 2.2.0.0 of the Cabal library

[alexbiehl]

I think this code hasn't changed for quite some time. I run out of haskell time now, but if you want, you could experiment a bit. As I showed the code is there, maybe it's a bug? Maybe your module ref is hot parsed as a DocModule or something? tomjaguarpaw <notifications@github.com> schrieb am Sa., 7. Apr. 2018, 12:12:

…

You mean what am I asking for is already implemented? Which Haddock version? I am using Haddock version 2.17.2 which came with Debian's ghc package (version 8.0.1). — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#796 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AByiiUIS00ob8rHpPoFtA3DKOLbze5biks5tmJDpgaJpZM4TK-m-> .

[tomjaguarpaw]

OK, thanks for looking into it. For now I am just making a redundant import to get the behaviour that I want and I will live with that for a while.

[alexbiehl]

Ok, I tried locally with haddock-2.19.0:

module X where

-- | See "GHC.Tuple"
data P a b = P a b 

with

haddock -html X.hs --read-interface /usr/local/share/doc/ghc-8.4.1/html/libraries/ghc-prim-0.5.2.0/,/usr/local/share/doc/ghc-8.4.1/html/libraries/ghc-prim-0.5.2.0/ghc-prim.haddock

And it worked out great!

[tomjaguarpaw]

Interesting. I will have to try with an updated Haddock. Thanks!