[commit: haddock] master: Add short documentation for hyperlinker source map type. (b6e9968)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/haddock

On branch  : master
Link       : http://git.haskell.org/haddock.git/commitdiff/b6e9968643bc0ab6c61289ecee7205e4d7bc421a

>---------------------------------------------------------------

commit b6e9968643bc0ab6c61289ecee7205e4d7bc421a
Author: Łukasz Hanuszczak <lukasz.hanuszczak at gmail.com>
Date:   Mon Jul 6 17:26:49 2015 +0200

    Add short documentation for hyperlinker source map type.


>---------------------------------------------------------------

b6e9968643bc0ab6c61289ecee7205e4d7bc421a
 haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs b/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs
index c3954dc..5f4dbc8 100644
--- a/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs
+++ b/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs
@@ -70,6 +70,15 @@ data SrcPath
     = SrcExternal FilePath
     | SrcLocal
 
+-- | Mapping from modules to cross-package source paths.
+--
+-- This mapping is actually a pair of maps instead of just one map. The reason
+-- for this is because when hyperlinking modules in import lists we have no
+-- 'GHC.Module' available. On the other hand, we can't just use map with
+-- 'GHC.ModuleName' as indices because certain modules may have common name
+-- but originate in different packages. Hence, we use both /rich/ and /poor/
+-- versions, where the /poor/ is just projection of /rich/ one cached in pair
+-- for better performance.
 type SrcMap = (Map GHC.Module SrcPath, Map GHC.ModuleName SrcPath)
 
 mkSrcMap :: Map GHC.Module SrcPath -> SrcMap