[haddock] #13: Module references in doc strings are always assumed to be in the current package

[haddock]

#13: Module references in doc strings are always assumed to be in the current
package
-------------------+--------------------------------------------------------
Reporter:  waern   |        Owner:       
    Type:  defect  |       Status:  new  
Priority:  major   |    Milestone:  2.4.2
 Version:  0.x     |   Resolution:       
Keywords:          |  
-------------------+--------------------------------------------------------
Comment (by duncan):

 A harder case is when a package refers to modules from another package
 that it does not even depend on.

 For example my `tar` package refers to modules from the `zlib` and `bzlib`
 packages. This is because it is showing examples of how to use the `tar`
 code to handle compressed `.tar.gz` files.

 It's not reasonable in this context to expect haddock to resolve the
 names, since they are certainly not in scope (and need not even be
 installed). I suggest that in such odd circumstances we allow fully
 package-qualified names.

 GHC uses the convention that fully package-qualified names use the `:` as
 a separator. For example I would use something like:

 {{{
 -- | Tar files are commonly used in conjuction with gzip compression,
 -- as in \"@.tar.gz@\" or \"@.tar.bz2@\" files. This module does not
 -- directly handle compressed tar files however they can be handled
 -- easily by composing functions from this module and the modules
 -- "zlib:Codec.Compression.GZip" or "bzlib:Codec.Compression.BZip".
 }}}

 What makes this harder though is that we do not know which version of
 those packages to link to. We could just take it literally and hope that
 the unversioned url points to the latest version or something. We could
 allow (but probably discourage) versioned fully qualified links like:

 {{{
 -- "zlib-0.5.0.0:Codec.Compression.GZip" or
 -- "bzlib-0.5.0.0:Codec.Compression.BZip".
 }}}

 So from haddock's point of view these could just be the package name,
 which may or may not include a version. The http link we construct would
 follow literally the given package name (including version if given).

-- 
Ticket URL: <http://trac.haskell.org/haddock/ticket/13#comment:6>
haddock <http://www.haskell.org/haddock>
Haddock, The Haskell Documentation Tool