Document haddock-options

[goldfirere]

Describe the bug
I do not know whether to add an idea to a .cabal file or to a cabal.project file.

More concretely: I needed to pass an extra flag to haddock during documentation building. Given the existence of ghc-options in a .cabal file, I tried a haddock-options field there. That did not work. Instead, I had to make a cabal.project file with a package stanza and put the haddock-options in the stanza.

haddock-options is not listed in https://cabal.readthedocs.io/en/3.4/cabal-package.html, but all users of my package will need this haddock option, so somehow cabal.project seems like the wrong place. (My understanding, which might be flawed, is that cabal.project should be for local options, while .cabal is for options that go with the package.)

haddock-options is also not listed in https://cabal.readthedocs.io/en/3.4/cabal-project.html, even though it is actually allowed there.... but I was able to figure things out based on the gloss "In general, the accepted field names coincide with the accepted command line flags that cabal install and other commands take." at the top of that page.

Expected behavior
I would expect haddock-options to be accepted in a .cabal file. But if that's the wrong design, then I would still expect haddock-options to be documented in the manual.

Additional context
Really, I'm trying to get cabal to play nicely with plugins, but that's beyond just this ticket.

[gbaz]

This doesn't say where options go per-se, but cabal.project is options for developing a package and cabal.project.local is options for locally developing a package (i.e. machine-specific specialization of the former). The rule of thumb is no .project goes in a distribution tarball, cabal.project goes into the github repo, and cabal.project.local doesn't even go there.

Which does give a hint -- as end users will want to haddock a distribution tarball, clearly the haddock options should be settable in *.cabal.

[Mikolaj]

Actually I do put my cabal.project into extra-source-files so that it ends up in the package archive, in the vain hope that some day build tools will honour, e.g., this bit from my cabal.project:

 package splitmix
    flags: +optimised-mixer

I don't think we will ever be able to specify this in .cabal file, so that leaves me no other option, both for development and package archive.

[amigalemming]

See this older ticket: #926