--enable-documentation behavior is undocumented

[Hrothen]

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]

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]

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]

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