Type class instances: link to source

[MartijnVanSteenbergen]

Currently the detailed documentation of a type class lists known instances of the type class. It'd be really helpful if the instances linked to their source wherever possible.

[PHO]

I really want this feature too, as instance declarations are rarely documented while their behaviours aren't always obvious.

[anonymous]

Milestone 2.7.0 deleted

[byorgey]

This came up again today on the libraries@ mailing list (and I would also love to see this feature), so I spent some time trying to figure out what would be necessary to implement this. Here are my (quite sketchy) notes:

     src/Haddock/Backends/Xhtml/Decl.hs:

       + ppDecl calls
         + ppDataDecl which calls
           + ppInstances which calls
             + Xhtml/Layout.hs:subInstances -- does actual generation
               of html for instances list.

       ppDataDecl gets a [DocInstance DocName];

       type DocInstance name = (InstHead name, Maybe (Doc name)) --
       from src/Haddock/Types.hs

       type InstHead name = ([HsType name], name, [HsType name])

       So already at this point we've forgotten source location
       information.  But if we had the information in the DocInstance
       type we could output it here.

       Tracing instances info backwards from ppDecl:

       + ppDecl is called from...
       + Haddock.Backends.Xhtml.processExport -- gets instance list from
	 pattern-matching on (ExportDecl ...) :: ExportItem DocName.
       + called from ifaceToHtml, mapped over "exports", defined as 
	 exports = numberSectionHeadings (ifaceRnExportItems iface)

	 ifaceRnExportItems is a record selector.

       + called from ppHtmlModule (iface passed along)
       + called from ppHtml, mapped over visible_ifaces, which is
         filtered from argument ifaces.

       + ppHtml called from Main.hs:render.  render gets ifaces as
         argument.

       + render called from renderStep, which passes on argument
         interfaces.
       + render called from main.  interfaces argument comes from call
         to readPackagesAndProcessModules.
       + readPackagesAndProcessModules gets ifaces from call to
         processModules.
       + processModules is in Haddock.Interface.

	 This is the point at which I ran out of steam. But the hope
         is that somewhere in processModules or functions called by
         it, the actual source location information of instances is
         available.

	 The DocInstance type would have to be modified to store
	 source location info.