haddocks incorrectly parses UNPACK pragma

[chessai]

This might be a problem with cabal new-haddock, but given that it fails in a parsing stage, I think it's haddock causing the problem. Let me know if you think I should open up the issue on cabal as well/instead.

#GHC version
$ ghc --version
The Glorious Glasgow Haskell Compilation System, version 8.4.2

#cabal version
$ cabal --version
cabal-install version 2.2.0.0
compiled using version 2.2.0.1 of the Cabal library

#haddock version
$ haddock --version
Haddock version 2.20.0, (c) Simon Marlow 2006
Ported to use the GHC API by David Waern 2006-2008

#Operating System
$ lsb_release -a
No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 16.04.4 LTS
Release:	16.04
Codename:	xenial

#Replicate
$ git clone git@github.com:chessai/freq && cd freq
freq$ nix-shell
nix-shell$ cabal new-build #this will succeed
nix-shell$ rm -rf dist*
nix-shell$ cabal new-haddock #this will fail with the following:
Build profile: -w ghc-8.4.2 -O1
In order, the following will be built (use -v for more details):
 - freq-0.1.0.0 (lib) (first run)
Preprocessing library for freq-0.1.0.0..
Running Haddock on library for freq-0.1.0.0..
Haddock coverage:

src/Freq/Internal.hs:208:3: error:
    parse error on input ‘{-# UNPACK’
    |
208 |   {-# UNPACK #-} !ByteArray -- ^ Square two-dimensional array of Double, maps first char and second char to probability
    |   ^^^^^^^^^^
cabal: Failed to build documentation for freq-0.1.0.0.

Most of the above was inside of a nix-shell.
I tried to create a minimal example of just a module with a similarly laid-out (textually) data type, like so:

{-# LANGUAGE BangPatterns #-}

module Example
  ( -- * The Foo type
    Foo(..)
  ) where

data Foo = Foo
  {-# UNPACK #-} !Int
  {-# UNPACK #-} ![Int]

but haddock parses this correctly, under the same setup, inside of the same nix shell.

[chessai]

When I switch the textual layout of the data type from

data FreqTable = FreqTable
  {-# UNPACK #-} !Int
  {-# UNPACK #-} !ByteArray
  {-# UNPACK #-} !ByteArray

to

data FreqTable = FreqTable {-# UNPACK #-} !Int {-# UNPACK #-} !ByteArray {-# UNPACK #-} !ByteArray

then haddock parses it correctly.

[andrewthad]

This does seem like an issue with haddock. However, in the meantime, here's a workaround: GHC automatically adds UNPACK pragmas to strict single-constructor single-field data types when -O2 is on. So, in your original example where you are unpacking ByteArray, you can just remove the UNPACK, and as long as you are building with -O2, it will still be unpacked.

[chessai]

@andrewthad

I changed

data FreqTable = FreqTable
  {-# UNPACK #-} !Int
  {-# UNPACK #-} !ByteArray
  {-# UNPACK #-} !ByteArray

to

data FreqTable = FreqTable
  !Int
  !ByteArray
  !ByteArray

then

nix-shell$ cabal new-haddock
Build profile: -w ghc-8.4.2 -O1
In order, the following will be built (use -v for more details):
 - freq-0.1.0.0 (lib) (first run)
Preprocessing library for freq-0.1.0.0..
Running Haddock on library for freq-0.1.0.0..
Haddock coverage:

src/Freq/Internal.hs:208:3: error: parse error on input ‘!’
    |
208 |   !ByteArray -- ^ Square two-dimensional array of Double, maps first char and second char to probability
    |   ^
cabal: Failed to build documentation for freq-0.1.0.0.

[chessai]

changing

data FreqTable = FreqTable
  !Int
  !ByteArray
  !ByteArray

to

data FreqTable = FreqTable !Int !ByteArray !ByteArray

lets cabal new-haddock succeed.

I think this isn't a problem with the UNPACK pragma itself, it seems more to do with the newline after the data constructor

[chessai]

Removing the bangpatterns also does not cause haddock to successfully parse the file.

[harpocrates]

Haddocks of this form on constructor arguments aren't supposed to work until GHC-8.6. This works in GHC 8.6 but not 8.4:

 data Typ = Con
   Int  -- ^ field 1
   Int  -- ^ field 2

However, looks like the unpackedness and strictness marks are not being processed properly even in 8.6:

 data Typ = Con
   {-# UNPACK #-} !Int  -- ^ field 1
   {-# UNPACK #-} !Int  -- ^ field 2

Fails with

Unexpected UNPACK annotation: {-# UNPACK #-} !Int
UNPACK annotation cannot appear nested inside a type

I'll take a look at that last issue.

[chessai]

OK, thank you

[harpocrates]

Note that the GHC side of this should be now fixed in 8.6 too (ghc/ghc@0361fc0)!

[chessai]

Thank you @harpocrates !