haskell / haskell/cabal

Cabal haddock-related flags are inconsistent

Open
#6,568 2 comments 1 reaction 0 assignees View on GitHub
cabal-install: cmd/haddock documentation type: bug
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

**Describe the bug**
The [documentation](https://www.haskell.org/cabal/users-guide/nix-local-build.html?highlight=enable%20documentation#cfg-field-documentation) says that providing `--enable-documentation` command line flag and having `documentation: true` in `cabal.project` should have the same effect (minus tests/bench targets):

![image](https://user-images.githubusercontent.com/1394391/75643268-97347700-5c92-11ea-8bda-ffdee08bb9dd.png)

However, when I add `documentation: true` to my `cabal.project` file I get this result:
![image](https://user-images.githubusercontent.com/1394391/75643340-cd71f680-5c92-11ea-8ea4-640450e12285.png)

and with `--enable-documentation` flag get this result:
![image](https://user-images.githubusercontent.com/1394391/75643377-ec708880-5c92-11ea-955c-74c2c4b3a936.png)

Note that with `documentation: true` field no links are generated for externally defined types except if they are defined in `base`.

It is either a bug in propagating flags or the feature is not documented clearly/correctly.

**To Reproduce**
1. Get a library that has dependencies from Hackage (not `base`)
2. Add `documentation: true` to `cabal.project`
3. Build the library: `cabal v2-build all`
4. Open generated documentation
5. Observe missing links
6. Build again with `cabal v2-build all --enable-documentation`
7. Observe that externally defined types are hyperlinked

**Expected behavior**
In both cases I would expect externally defined types to be hyperlinked.

Alternatively (if it is a documentation bug) I would expect the documentation to mention extra parameters to be added to `cabal.project` in order to have externally defined types hyperlinked.

**System information**
- Linux, MacOS
- `cabal-3.0.0.0`, `ghc-8.6.5`, `haddock-2.22.0`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.