Add Haddock-Options field to Cabal package description #926
Comments
|
(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. |
|
(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. |
|
(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? |
|
(Imported comment by guest on 2012-04-02) The feature request for the --qual option is in this ticket: 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, |
|
(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. |
|
I wanted to write documentation that links to #if HADDOCK
import A
#endif |
|
@liyang So you want to be able to write |
|
@23Skidoo Perhaps. But this is a more general solution. |
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
|
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: But that gets a bit ugly. Perhaps haddock needs a haddock-only import pragma, like: so that then I can do it unqualified in the doc comments: |
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
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 haskell#926) Fixes haskell#1237.
Thanks to milkypostman for providing the patch. Closes ticket haskell#926.
(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.
The text was updated successfully, but these errors were encountered: