cabal/haddock features

[Duncan Coutts]

On Tue, 2006-12-05 at 13:34 +0100, Johannes Waldmann wrote:
> yeah, great tools, but ..

Thanks for the comments.

Some of these could usefully be turned into bug reports, that way we
will not forget them:

http://hackage.haskell.org/trac/hackage/

log in with username guest and password haskell' (note the apostrophe at
the end)

> * when Cabal(-1.1.6) sees a wrong entry in "exposed-modules"
>   (a module whose source cannot be found)
>   it says "Parse of field 'exposed-modules' failed:"
>   with an unhelpful line number (the line where the field starts,
>   not the line where the error occurs)

We're using the ReadP parser lib. I'm not sure we can do a lot better
without changing libs.

Any suggestions anyone?

Note that depending on non-core packages is out as that'd make
bootstrapping hard.

> * is there a simple way to "expose" all modules in a source tree?
>   Perhaps: exposed-modules: Foo.Bar.*; Baz.*
>   I have to generate "exposed-modules" by some find/sed hackery,
>   But I want to use Cabal exactly to avoid such extra tools.

At the moment you have to list them all explicitly. I don't think we're
against relaxing that but we'd need proper dependency analysis to figure
out what is needed. At the moment Cabal does no dependency analysis, it
leaves that up to the compiler.

Eventually we'll need to do that properly. For example it's essential to
deal with non-trivial pre-processors like c2hs, so if/when we get that
we could look at relaxing the requirement to list all exposed and hidden
modules.

> * when a *.cabal file specifies both a library and an executable
>   that uses this library, the build process compiles all files twice,
>   once for the library, once for the executable?
>   (This may be my misunderstanding of some options/fields.)

The problem is that the modules need not be compiled using the same
flags, so to be safe they get compiled twice. One could optimise that by
checking if the flags are indeed exactly the same, however the
prevailing opinion seems to be that we should make .cabal files contain
executables or libraries but not both. So you'd just make an executable
that depends on the lib. We also need to make it easier to work with a
bundle of related .cabal packages in that case (which we need anyway for
larger projects).

> * haddock(-0.8) does not understand ghc-6.6's new syntax,
>   e.g. foo :: Bar <- baz  (withouth parens around the lhs)
>   that is bad because now I have to rewrite my code.

Haddock doesn't understand a great deal of the GHC syntactic extensions.
The right solution here is to make haddock use the GHC api to parse the
file. The first part of this project is done. GHC can now parse haddock
documentation markup.

> * why does haddock *die* in such cases? it has no business
>   parsing the code anyway, as it should only care for declarations.
>   (yes it needs to find the next declaration
>   but couldn't this be done more generously?)
>   (no, since what looks like a decl. could in fact be inside
>   a block comment - but that's already known after scanning,
>   and before proper parsing?)

It does currently parse the code. Making it more liberal would be
tricky, but anyway the right solution is to use the GHC API which
obviously can parse all the syntactic extensions.

> I'd try to help by coding some patches but I don't follow
> the development closely, so I ask if perhaps someone already is
> working in it or at least has a roadmap for work.

We could certainly do with help on any of the above issues.

Duncan