could hpack generate haddock documentation?

[pjljvandelaar]

We are considering moving from Cabal to hpack.
We check to have a 100% coverage with haddock,

With HPack we get

stack haddock .
...
�Haddock coverage:
   0% (  0 /  9) in 'Paths_txs_sort'
  Missing documentation for:
    Module header
    version (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:28)
    getBinDir (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:39)
    getLibDir (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:39)
    getDynLibDir (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:39)
    getDataDir (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:39)
    getLibexecDir (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:39)
    getDataFileName (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:47)
    getSysconfDir (.stack-work\dist\67675594\build\autogen\Paths_txs_sort.hs:39)

This would break our build....

Since the offending code is generated anyway, could you also generate some documentation as well.
It would satisfy haddock and your users might profit as well when they look at the generated file.

[sol]

Paths_txs_sort is not generated by Hpack.

You might want to report this at commercialhaskell/stack.

My assumption is that this file is generated by Cabal, so I'm surprised that this did not affect you when you used the cabal executable instead of stack.

@snoyberg @mgsloan does stack use custom code for haddock or something?

[snoyberg]

IIUC, what's happening is:

• hpack by default includes the Paths_ generated modules in the other-modules generated list
• If that module is not in the list, then Haddock ignores it, and its lack of docs does not affect doc coverage

It seems like the most straightforward workaround would be to add some config option to hpack to not include the Paths_ module. A more thorough, but much more difficult route, would be to get a PR merged into Cabal itself so that when it generates the Paths_ modules, it includes Haddocks on each exported identifier.

[tfausak]

add some config option to hpack to not include the Paths_ module

It's not exactly that, but setting other-modules: [] does the trick.

[sol]

Yes, as @tfausak hinted, if you do not want the Paths_* module included, then a workaround is to specify other-modules explicitly.

By now I think it would be cleaner not to include Paths_* by default and let users specify it in generated-other-modules explicitly if needed. But it's a breaking change, so if we do it we need a migration path.

[sol]

Closing in favor of #303. Feedback and suggestions are very much welcome!