Comments on: Cross-package documentation, part 1

By: David Waern

David Waern — Thu, 25 Jun 2009 21:16:45 +0000

Andrea: that might be possible to do in the future, since it should be possible to fully re-create the interface given the .hi files and the .haddock file provided that we put in some missing bits in the .haddock file. Note that othing is missing for cross-package documentation, but if you want to re-generate documentation or create a hoogle file, we need to put some more bits into the .haddock file. This is not in scope of Isaac’s project, though.

By: Andrea Vezzosi

Andrea Vezzosi — Thu, 25 Jun 2009 15:41:32 +0000

The motivating goal for me was keeping a central hoogle index of all the packages installed, and finding that while packages shipped with ghc have the .haddock interface installed you can’t currently extract the .txt file to feed hoogle from it.

By: David Waern

David Waern — Thu, 25 Jun 2009 09:21:50 +0000

The doc strings are already in the .haddock files! This is stated in the wiki-page we wrote about this task:

http://trac.haskell.org/haddock/wiki/CrossPackageDocumentation

By: haddock2009

haddock2009 — Thu, 25 Jun 2009 05:34:54 +0000

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

By: haddock2009

haddock2009 — Thu, 25 Jun 2009 00:37:14 +0000

Andrea: nope. I believe the missing bits of information are the doc-strings, which I plan to include in the .haddock files; and the type-signatures, which my current plan is to retrieve from .hi files. Luckily .hi files are present in binary distributions, so your idea might work. Do you have a particular use-case? Like, letting the end-user turn their docs into whatever strange format they like, as long as Haddock supports it? (or even machine-processable. hmm. Haddock and GHC and .hi/.haddock file versions are all very tightly coupled at the moment, by the way.)

thanks!
-Isaac

By: Andrea Vezzosi

Andrea Vezzosi — Wed, 24 Jun 2009 23:14:32 +0000

this blog is becoming a nice resource for wannabe haddock hackers
so i’ll try asking here:
does the .haddock interface file contains enough information to generate e.g. the documentation for that module? i’m guessing the answer is no.
that’s a bit unfortunate though, since a machine-readable format to ship documentation that can be then converted in a desired format would be quite useful, especially when one uses binary tarballs for libraries (like when installing ghc).

By: David Waern

David Waern — Wed, 24 Jun 2009 20:43:02 +0000

You didn’t say anything wrong here, so I’ll just answer your questions

During HTML generation, the declarations are taken from ifaceRnExportItems which represents the export items. See the ExportItem the data type – it contains LHsDecl. Creating the export items is one of the most important jobs of Haddock.Interface.Create.

You were wondering which names are documented in a given modules’s instDocMap. That is the names of all declarations in that module, that have documentation. It is the same as ifaceRnDocMap in Interface, which is generated from ifaceDeclMap by taking all declared names that have documentation and renaming the documentation. ifaceDeclMap is just a map of all declarations in the module.

Haddock could be a lot better documented here.