Ticket #157 (new defect)

Opened 3 years ago

Last modified 19 months ago

Push/improve Haddock API and .haddock files usage

Reported by: claus Owned by:
Priority: major Milestone:
Version: 2.7.2 Keywords: API, interface files
Cc:

Description

I'd expect Haddock processing to involve three stages:

  1. extract information for each file/package
  1. mix and match information batches for crosslinking
  1. generate output for each file/package

where the results of 1 should be available .haddock files, so that stage 2/3 tools can start from there if source isn't available, and the results of 2 should be exposed in the API, so that it can be shared between backends.

Currently, backends such as --hoogle can't start from .haddock files, and stage 2 processing is duplicated in what should be stage 3-only backends. It might also be useful to think about the representation of the output of stage 2 above: currently, Haddock directly generates indices in XHtml form, even though much of the index computation should be shareable accross backends.

Relatedly, the Haddock executable should be a thin wrapper over the Haddock API, if only to test that the API exposes sufficient functionality for implementing everything Haddock can do.

Instead, there is an awful lot of useful code in Haddock's Main.hs, which is not available via the API. So when coding against the API, for instance, to extract information from .haddock files, one has to copy much of that code.

Also, some inportant functionality isn't exported (e.g., the standard form of constructing URLs), so it has to be copied and kept in synch with the in-Haddock version of the code.

Overall, it seems that exposing sufficient information in the API, and allowing .haddock interface files as first-class inputs, there should be less need for hardcoding external tools into Haddock (such as --hoogle, or haddock-leksah). Instead, clients should be able to code alternative backends separately, using Haddock to extract information from sources into .haddock files, and the API for processing those .haddock files.

(splitting Haddock into frontend/indexer/backend would be better than similar documentation plugin functionality available, for instance, in Javadoc doclets, for alternate output formats.)

More documentation about the role and usage of these two Haddock features (API, .haddock files), as well as the plans for their development would also be useful.

Mailing list thread: http://www.haskell.org/pipermail/haskell-cafe/2010-October/085434.html

Attachments

haddock-index.hs (9.4 kB) - added by claus 3 years ago.
generate text index of haddock urls, from .haddock files and ghc-pkg database

Change History

Changed 3 years ago by claus

generate text index of haddock urls, from .haddock files and ghc-pkg database

Changed 3 years ago by claus

Here is an example application (generating text index of haddock docs, from .haddock files and ghc-pkg database, for use in Haskell IDEs; the format is close to what haskellmode for Vim uses). The code is somewhat frankensteinish at the moment, with pieces copies together from non-exposed haddock functionality.

Btw, I'm pretty sure that haddock's --hoogle could be made to work from .haddock and .hi files (currently, it seems to want input source?), so that hoogle's .txt files could be reconstructed without sources (module comments seem to be missing, and patching in types from .hi files might be some work).

Changed 19 months ago by anonymous

  • milestone 2.7.0 deleted

Milestone 2.7.0 deleted

Note: See TracTickets for help on using tickets.