Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Add Haddock-Options field to Cabal package description #926

Open
bos opened this Issue May 24, 2012 · 9 comments

Comments

Projects
None yet
6 participants
Contributor

bos commented May 24, 2012

(Imported from Trac #936, reported by guest on 2012-04-01)

Currently when running 'runhaskell Setup haddock' I can pass options to Haddock with the --haddock-option and --haddock-options option. I would like to add some options in a Cabal description file analogously to the GHC-Options fields and others.

Contributor

bos commented May 24, 2012

(Imported comment by @dcoutts on 2012-04-01)

What would you want to add?

In general we think it's inappropriate for the package author to specify haddock options, only the package builder.

Contributor

bos commented May 24, 2012

(Imported comment by guest on 2012-04-02)

I want to set the qualification style with the '--qual' option. This is new in Haddock-2.10. Since the qualification style depends on the used identifier convention, it is something that the package author should choose.

If you think that general Haddock options do not fit into a Cabal file, maybe we can look for a subset of Haddock options and handle them in a special way. This could be similar to Extensions, where using the Extensions field is prefered to writing GHC-Options: -XExtension.

Contributor

bos commented May 24, 2012

(Imported comment by @dcoutts on 2012-04-02)

Hmm, but this isn't something that authors want to specify on a per-file/module basis like other haddock directives?

With haddock, the usual rule of thumb is that author-specified directives go in the source files themselves (e.g. hide, pune etc) while things the builder should specify are command line options (which we partially reflect as cabal haddock features or via --haddock-options).

I found the bit in the user guide for --qual but I have to admit it's not clear to me the purpose or who should be setting it, and if it's really a package global or module local option. Is there any ticket or other discussion that gives some explanation or motivation for the feature?

Contributor

bos commented May 24, 2012

(Imported comment by guest on 2012-04-02)

The feature request for the --qual option is in this ticket:
http://trac.haskell.org/haddock/ticket/22
I am currently adding a mode that is close to the proposed 'orig' qualification mode.

Currently Haddock only allows to set the qualification style globally. The reason is that you normally choose one style of identifiers for a whole package. E.g. identifiers in the 'stm' package always contain a suffix that reflects the module. You will usually write them unqualified. In contrast to that package 'bytestring' re-uses the same function names in different modules of the package and function names that are already present in Prelude. Thus you will certainly use those identifiers in a qualified way.

In principle we could add a Haddock-PRAGMA for a per-module setting,
but this seems to be less useful.

Contributor

bos commented May 24, 2012

(Imported comment by @dcoutts on 2012-04-03)

I think I see. So yes, it is a little like the current default-extensions: field which applies the extensions to all the modules in the package so you don't have to use LANGUAGE pragmas in each module. What I don't want is to have a general haddock-options field because most options are not applicable. Another alternative is to heavily restrict the allowed options, as we do for ghc, but a more explicit approach might be better.

It's really a haddock global style thing, e.g. if haddock ever decided to allow markdown and that were enabled by a flag, that would be a similar one where it's the package author who decides.

Contributor

liyang commented Feb 18, 2013

I wanted to write documentation that links to module A without explicitly qualifying everything, where A is not directly imported. I was hoping for a workaround along the lines of:

#if HADDOCK
import A
#endif
Member

23Skidoo commented Feb 19, 2013

@liyang So you want to be able to write haddock-options: --optghc=-DHADDOCK ? I think it'd be easier to modify Haddock to always pass -DHADDOCK to GHC.

Contributor

liyang commented Feb 22, 2013

@23Skidoo Perhaps. But this is a more general solution.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Mar 15, 2013

Make 'cabal haddock' always define __HADDOCK__ CPP macro.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Mar 15, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Mar 15, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.
Member

dcoutts commented Mar 15, 2013

The cpp approach is not awful but it'd be nicer if haddock could do something more directly here since it's a common issue. I believe you can reference things that are not imported if you fully qualify them, like:

-- | This function can be used with 'Foo.Bar.baz'
foo :: ..

But that gets a bit ugly. Perhaps haddock needs a haddock-only import pragma, like:

{-# HADDOCK import Foo.Bar #-}

so that then I can do it unqualified in the doc comments:

-- | This function can be used with 'baz'
foo :: ..

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Mar 19, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Apr 15, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Apr 23, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue May 2, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue May 11, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue May 13, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Jul 17, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Jul 17, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Jul 19, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Aug 23, 2013

Make 'cabal haddock' always define __HADDOCK__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Aug 26, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Sep 5, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Sep 7, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Oct 7, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Oct 12, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Oct 14, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

23Skidoo added a commit to 23Skidoo/cabal that referenced this issue Oct 16, 2013

Make 'cabal haddock' define __HADDOCK_VERSION__ when preprocessing.
This is useful e.g. for "writing documentation that links to module A without
explicitly qualifying everything, where A is not directly imported." (see the
discussion in #926)

Fixes #1237.

@23Skidoo 23Skidoo modified the milestones: Cabal-1.22, Cabal-1.18 Apr 20, 2014

@ttuegel ttuegel modified the milestones: Cabal-1.24, Cabal-1.22 Apr 23, 2015

@23Skidoo 23Skidoo modified the milestones: Cabal 1.24, Cabal 1.26 Feb 21, 2016

@ezyang ezyang modified the milestone: Cabal 2.0 Sep 6, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment