Haddock hyperlinks and without warning about redundant imports

Question

I have a dummy module in my project, whose sole purpose is to hold Haddock documentation for the rest of the library. In fact I don't need to import anything in this module, but if I don't import other modules, Haddock doesn't hyperlink function names to their modules.

My module looks like this

{- |

Lots of Haddock text here... it references 'someFunction'.

-}
module TopLevelDoc () where

import Other.Module.With.SomeFunction

Now if I build the project, I get this warning:

    Warning: The import of `Other.Module.With.SomeFunction' is redundant
           except perhaps to import instances from `Other.Module.With.SomeFunction'
         To import instances alone, use: import Other.Module.With.SomeFunction()

If I remove imports or make them (), Haddock doesn't hyperlink someFunction to its documentation. If I leave such imports as is, I get lots of false warnings, which I don't like. And I don't want to suppress this kind of warning for the entire project, it may be useful for any other module but this one.

Questions:

1. How do I get hyperlinked Haddock output without such warnings when building?
2. Is it possible to disable warnings on per-file basis? (like I can do it globally with ghc-options in .cabal)

Answer 1

To silence the unused import warning, you can put a pragma at the top of your file:

{-# OPTIONS_GHC -fno-warn-unused-imports #-}

You can link to to identifiers that aren't in scope by explicitly qualifying them:

It is also possible to refer to entities that are not in scope in the current module, by giving the full qualified name of the entity:

-- | The identifier 'M.T' is not in scope

If M.T is not otherwise in scope, then Haddock will simply emit a link pointing to the entity T exported from module M (without checking to see whether either M or M.T exist).

— The Haddock User Guide

However, this will probably make your documentation source quite ugly, and the module qualifications aren't removed from the output, so I'd recommend turning off the warnings instead.