[Haddock] [haddock] #157: Push/improve Haddock API and .haddock files usage

haddock haddock at projects.haskell.org
Thu Nov 4 12:28:44 EDT 2010


#157: Push/improve Haddock API and .haddock files usage
-------------------+--------------------------------------------------------
Reporter:  claus   |       Owner:                      
    Type:  defect  |      Status:  new                 
Priority:  major   |   Milestone:  2.7.0               
 Version:  2.7.2   |    Keywords:  API, interface files
-------------------+--------------------------------------------------------
 I'd expect Haddock processing to involve three stages:

   1. extract information for each file/package

   2. mix and match information batches for crosslinking

   3. 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
 [http://www.oracle.com/technetwork/java/javase/documentation/index-
 jsp-135444.html 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

-- 
Ticket URL: <http://trac.haskell.org/haddock/ticket/157>
haddock <http://www.haskell.org/haddock>
Haddock, The Haskell Documentation Tool


More information about the Haddock mailing list