[Haddock] Fwd: Fully qualified identifiers

[David Waern]

Forgot to copy this list. Here's some help regarding rendering of
names in Haddock:

---------- Forwarded message ----------
From: David Waern <david.waern at gmail.com>
Date: 2010/8/26
Subject: Re: [Haddock] Fully qualified identifiers
To: Tobias Brandt <tob.brandt at googlemail.com>


2010/8/26 Tobias Brandt <tob.brandt at googlemail.com>:
> On 26 August 2010 12:50, David Waern <david.waern at gmail.com> wrote:
>> If you want to take a look at it yourself
>> then we can try to help out by telling you where to look and so on. I
>> think full qualification would be quite easy to implement, since the
>> backends in Haddock have that information available already. The
>> "orig" qualification style would take a bit more work, I suppose.
>
> Great! I'd be grateful for some pointers on where to begin.
>

For full qualification, you want to look at
Haddock.Backends.Xhtml.Name. The function ppDocName is used to
generate HTML for links in the documentation.

We can see that it only uses the "OccName" part of the Name data type
(since it uses ppOccName and getOccString). To enable full
qualification, we must print the module name as well, which is in
Name. Both Name and OccName are part of the basic data types provided
by the GHC API. You can  take a look at this page in the GHC
commentary to get accustomed to these types:

 http://hackage.haskell.org/trac/ghc/wiki/Commentary/Compiler/KeyDataTypes

However, all we need to do really is to get the module of a Name, and
for that maybe the Haddock documentation is better:

 http://www.haskell.org/ghc/docs/6.12.2/html/libraries/ghc-6.12.2/Name.html

Then of course, you need to thread around some flag in the Xhtml
backend that says which qualification mode to use. We're already
threading around various flags and information in the backend. This
area could use some cleanup. It would be good to at least group such
information in a data type, if possible. If you feel inclined you're
welcome to tackle this problem, but you don't have to.

I guess the flag could look something like this:

data Qualification = None | Original | Full

It should be added to Haddock.Types.

Adding command line flags is simple, just have look in Haddock.Options.

I think doing all of the above is a good warmup before tackling the
slightly harder problem of Original qualification. I don't know if the
original qualification is available in the GHC Name/OccName. If not
then we will have to add this information to Haddock's DocName type
somehow.

Hope this helps,
David