search

haskell / cabal

Official upstream development repository for Cabal and cabal-install
https://haskell.org/cabal
Other
1.62k stars 691 forks source link

--enable-documentation behavior is undocumented #7879

Open Hrothen opened 2 years ago

Hrothen commented 2 years ago

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.

Mikolaj commented 2 years ago

I've had a quick look at the development version of the manual

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

and it seems the problem persists there? Am I right? Is anything that you describe fixed there?

In any case, we are very much open to brainstorming what exactly to put there and to a PR actually making the fix.

Hrothen commented 2 years ago

and it seems the problem persists there? Am I right?

Correct, there don't appear to be any changes.

The changes that need to be made depend on what the flag actually does, which aside from building docs for the dependencies I have not been able to determine. At a bare minimum that section in the manual needs to indicate the behavior, and the output of --help needs to be updated with an equivalent description, and the blurb about not having support for building docs for dependencies needs to be removed.

It seems likely that the flag should also be deprecated in favor of a new flag with a better name.

Hrothen commented 2 years ago

Update: It also seems to imply --haddock-quickjump