haskell / haskell/cabal

--enable-documentation behavior is undocumented

Open
#7,879 3 comments 0 reactions 0 assignees View on GitHub
attention: pr-welcome documentation type: enhancement
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

**Describe the bug**
Currently the documentation in the manual is only in the cabal.project section, for some reason no flags appear to be documented in the commands section any more.

```
Enables building of Haddock documentation

The command line variant of this flag is --enable-documentation and --disable-documentation.

documentation: true does not imply haddock-benchmarks, haddock-executables, haddock-internal or haddock-tests. These need to be enabled separately if desired.
```

And `cabal haddock --help` gives the even less useful `Enable building of documentation`

These provide no indication of what options will be passed to the haddock invocation, aside from a few flags that will explicitly _not_ be set. "Enables building of Haddock documentation" is also a confusing thing to say in a flag that is passed to `cabal haddock`, a command whose only purpose is building haddock documentation.

This flag also enables building documentation for dependencies, which the `--help` output for `cabal haddock` explicitly states isn't currently supported, I don't know if that should be a separate issue.

**To Reproduce**
Steps to reproduce the behavior:

Visit https://cabal.readthedocs.io/en/3.6/cabal-project.html?highlight=haddock#cfg-flag---enable-documentation

Or

```
$ cabal v2-haddock --help
```

**Expected behavior**
The behavior of the flag should be properly documented.

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.