On Mon, Jul 30, 2007 at 03:43:33PM +0100, Duncan Coutts wrote:
* haddock docs not building. This is very common. The most common parse problem is un-escaped / chars. This seems to trip people up a lot. I wonder if we could make haddock's parser grok this better? For example most uses of ' don't cause problems, eg "don't". I wonder if we could have a similar rule for / so that things like "I/O" didn't get recognised as beginning an emphasised section. Perhaps the rule should be that / but be at the beginning or end of a token, so a " / " or a "X/Y" would not count, only "/beginning" or "ends/" of words?
I think it would be better to encourage people to test haddocking more frequently, rather than to make its syntax more magical. Unfortunately I'm not sure how best to do that without it slowing down builds while developing. I've thought for a while that we should have a cabal-lint, that runs the sanity checks that hackage does before accepting an upload. Perhaps cabal-lint could also check that building and haddocking works, and run the packages testsuite too? People would then be encouraged to run that before uploading to hackage, and to the extent permitted by security concerns, hackage could run cabal-lint itself. Thanks Ian