Ticket #13 (closed defect: fixed)

Opened 7 years ago

Last modified 2 years ago

Module references in doc strings are always assumed to be in the current package

Reported by: waern Owned by:
Priority: major Milestone:
Version: 0.x Keywords:
Cc:

Description

We don't point module references ("..." in doc strings) to the correct package, they are always assumed to be modules in the current package.

Change History

Changed 6 years ago by anonymous

  • priority changed from minor to major

This is problematic for some of the core libraries

Changed 6 years ago by anonymous

Incidentally, I think the problem is the

DocModule str -> return (DocModule str)

in Haddock.Interface.Rename.renameDoc.

Changed 6 years ago by waern

  • milestone set to 2.4.2

Changed 6 years ago by waern

The problem here is that we only have a String representing the module. We should change DocModule? so that it takes a Module instead. The change needs to be done in GHC.

Changed 6 years ago by SamB

New duplicate: #81 (cross-package linking to modules doesn’t work).

Changed 6 years ago 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).

Changed 6 years ago by waern

  • milestone changed from 2.4.2 to 2.5.0

Changed 3 years ago by waern

  • status changed from new to closed
  • resolution set to fixed

Changed 2 years ago by anonymous

  • milestone 2.5.0 deleted

Milestone 2.5.0 deleted

Note: See TracTickets for help on using tickets.