Archive for June, 2009

cross-package, Plan A

June 25, 2009

I think my next step should be the simpler bit: extend .haddock files to contain their docs. (After doing that, I might have a better guess where best to thread in the type-signatures.)

Which means,

#1. That we need to write the info to .haddock files
#2. that we can parse it.
#3. that InstalledInterface can hold it
#4. find out if there’s anything we need to do to make use of the new info in InstalledInterface… well obviously there is :-)

A test case would be a package, that imports and re-exports anything that has a doc-string.  I could probably download haskell98 from hackage and use it as a test case.

This is out of order I’m sure: at least writing the info probably means we have to change InstalledInterface first, for example.  That’s what plans are for: trying them and refactoring them when they fail!

P.S. I’m doing an awful job at synchronizing my sleep cycle with SimonMar’s… it’s 2 a.m. U.S. East Coast time here, time for me to go to bed (or past time rather :-)

Cross-package documentation, part 1

June 24, 2009

It would appear to the casual observer that Haddock works fairly excellently cross-packages.  For example, I haddocked the Haddock code, and all the links to the types from the GHC API point to the haddock-docs in my GHC 6.10.3 installation.  (Yes, you need the versions of the dependent packages chosen, installed and haddocked, and this doesn’t always work out optimally online. But that’s not the problem that I’m confronting.)

Yes, links work.  But that’s about it, right now.  Compare (broken)  http://www.haskell.org/ghc/dist/stable/docs/libraries/haskell98/List.html to (good) http://www.haskell.org/ghc/dist/stable/docs/libraries/base/Data-List.html .  The broken one’s source (haskell98:List) imports the good one (base:Data.List).  haskell98:List’s documentation luckily lists the *names* of the exported things, because they’re listed in that file’s export list.  But not their types or their docs.  Not the module doc header (though that shouldn’t be copied anyway), and there’s no link to base:Data.List (which is acceptable. Although maybe someone should write a haddock-header to haskell98:List that says it’s the Haskell 98 version (specified at http://www.haskell.org/onlinereport/list.html ) of the slightly expanded base-package Data.List[link].

Anyway, the way we get any links to modules in other packages is because we read their generated .haddock files.  They’re binary and haddock doesn’t have any obvious way to make them human-readable, but they correspond to Haddock.InterfaceFile.InterfaceFile.  Which is, roughly, a list of Haddock.Types.InstalledInterface, which seems to be the interesting bit.

data InstalledInterface = InstalledInterface {
instMod            :: Module,
instInfo           :: HaddockModInfo Name,
instDocMap         :: Map Name (HsDoc DocName),
instExports        :: [Name],
instVisibleExports :: [Name],
instOptions        :: [DocOption],
instSubMap         :: Map Name [Name]
}

A Module (not to be confused with GhcModule, which is defined by Haddock) is a low-information type defined in GHC that contains the package name and version and the module name.

HaddockModInfo is just the module’s header description, plus the portability:, stability:, maintainer: fields (HaddockModInfo is defined in GHC, oddly enough: must be parse result. defined in ghc:HsSyn to be precise.)

DocOptions are hide, prune, ignore-exports, not-home. (defined in haddock code.)

The rest contain a lot of “Name”s, which is a GHC thing that refers unambiguously to the place an identifier originates.  Sufficient for making a link, but not sufficient by itself for copying the named identifier’s docs or type.  So passing over them for now… there is one interesting thing left.

A DocName contains a Name and also (if any) the module we’d like to link to in which that name is documented.  instDocMap :: Map Name (HsDoc DocName).  This gives more info on any number of Name identifiers.  (HsDoc provides formatting, DocName provides its references .)  There is no type information here at all, as far as I can tell, which will clearly need to be remedied somehow (in Interface, roughly a superset of InstalledInterface, types appears in ifaceDeclMap, though I’m not sure if that’s where they’re retrieved from for HTML-doc-printing).  But there’s another big question I need to find out: *which* names are documented in any given module’s instDocMap?  The type provides no clue, nor does its current (lack of a) doc string, nor ifaceRnDocMap.  I could look everywhere in the code that it’s generated, or I could ask David Waern… who will need to tell me if I said anything confused here anyway :-)

How To Navigate Your Code:

June 23, 2009

I’ve always wished I could document my own code with Haddock even when it isn’t exported.  Today I was exploring the Haddock code-base (which contains a fair number of Haddock-comments) and wanted an easier way to read it.

First I tried `cabal haddock –hyperlink-source`.  It only documented Distribution.Haddock because that’s the only exported module of the library!  `cabal haddock -v` told me that it was passing `–hide=all the other-modules` to haddock, which I couldn’t reverse with `cabal –haddock-option`.  The only way to “fix” that was to hack haddock.cabal so that all modules appear under an `exported-modules:` clause (which is only allowed under `library`, not `executable`, so I had to spuriously merge the executable section into the library section).  Yay!  Then I had to remove Haddock.Types’s {-# OPTIONS_HADDOCK hide #-} which was causing a bit of trouble.

Adding –haddock-option=–ignore-all-exports includes non-exported functions in the documentation, which can be helpful or unhelpful.  I wish it had a mode to include the un-exported stuff *after* all the exported stuff, with a clear separation.  As a side note, –ignore-all-exports also “breaks” docs of Distribution.Haddock and any module that re-exports things from other modules, currently…

HsColour is pretty cool too, but it would be even cooler if it hyperlinked all the identifiers in the source, like Haddock does… hmm.

EDIT: I forgot to attach my actual silly patch to Haddock.  Can’t find out how to get WordPress to let me upload it either. oh well, here it is: gee, I can’t even get it to turn into a link, here on Linux?: http://isaac.cedarswampstudios.org/2009/isaacs-silly-haddock-self-doc.dpatch


Follow

Get every new post delivered to your Inbox.