__color__,ticket,summary,milestone,type,created,_changetime,_description,_reporter
3,3,feature request: record types with partially exported fields,,enhancement,2008-06-17T01:39:02Z+0100,2009-03-25T18:09:56Z+0000,"  attached (M1) is an example of a situation, where haddock hides all fields of a record, just because one field is hidden. The result is that the other field is not shown in the documentation as well, even though it is exported.

  As an example for why hiding certain fields of a record might make sense, consider M2. There we export two functions for decomposing T: f and g, whereas f is a class function that can be used for other datatypes as well, and g is a function specific to T. The ugly fT function is hidden from the user.

  I'd wish myself a haddock output in which T would be shown in record style, but there would be a blank instead of fT or maybe something like ""<hidden>"". ",avatariks
5,5,Print an error message when given -optghc  instead of --optghc,,enhancement,2008-06-19T20:47:24Z+0100,2008-06-19T20:58:04Z+0100,"Since the flag --optghc is so similar to GHC's -optghc, and -optghc is interpreted as the -o flag with an argument (making Haddock silently accept it), it would good to give a warning message in this particular case to avoid mistakes.",waern
5,6,There should be a --maintainer flag,,enhancement,2008-06-19T20:57:40Z+0100,2008-06-19T20:57:40Z+0100,There should be a --maintainer flag to allow Cabal to pass the maintainer from the .cabal file to the generated docs.,waern
4,7,The docs should mention the module header,,enhancement,2008-06-19T21:00:54Z+0100,2008-11-03T09:12:47Z+0000,The docs should mention the module header stuff.,waern
3,10,Parsing module without explicit module declaration fails,_|_,defect,2008-06-19T22:05:58Z+0100,2012-10-16T10:02:18Z+0100,"If a module does not contain an explicit module declaration
'''and''' starts with
{{{
-- | some comment
}}}
then parsing fails.

This is a bug in GHC's parser.  It is only triggered if
[http://www.haskell.org/ghc/docs/latest/html/libraries/ghc/DynFlags.html#v:Opt_Haddock Opt_Haddock] is used.

=== Details ===
GHC's parser has a rule for Haddock comments on module headers.
When the parser sees the Haddock comment at the
beginning it then wants the next declaration to be a module header
(the grammar has an S/R conflict because of this).

One possible solution could be to parse Haddock comments separately from the Haskell code, and match up Haddock comments with AST nodes in a later step.

=== Steps to reproduce ===
{{{
-- | Hi there
main = print ""Hello World!""
}}}

Running
{{{
$ haddock Main.hs
}}}
fails with:
{{{
Main.hs:2:1: parse error on input `main'
}}}

In contrast both of the following example work just fine:

{{{
{-
Hi there
-}
main = print ""Hello World!""
}}}
{{{
foo = 23
-- | Hi there
main = print ""Hello World!""
}}}",waern
4,12,Haddock comments needs to be separated by semi-colons when explicit layout is used,,defect,2008-06-19T23:23:37Z+0100,2008-11-03T09:12:06Z+0000,"Haddock comments are parsed as separate declarations so we need to insert a ';' when using them with explicit layout:

{{{
module NoLayout where {
  -- | the class 'C'
  ;
  g :: Int;
  g = undefined
 }
}}}

This should be fixed in the GHC parser, hence the 2.3.0 milestone.",anonymous
4,14,Add a link to the documentation home of a re-exported entity,,enhancement,2008-06-19T23:44:26Z+0100,2008-06-19T23:47:55Z+0100,"For a non-home occurrence of an entity, we should point to the home location in the doc somehow.  This would help to distinguish multiple functions with the same name (eg. we don't know whether Prelude.catch is Control.Exception.catch vs. System.IO.Error.catch).",waern
4,15,"The Haddock comment lexer should handle ""...."" in doc strings",,defect,2008-06-19T23:47:10Z+0100,2008-06-19T23:47:10Z+0100,"The lexer should handle ""...."" in doc strings, only recognising it if the contents looks like a module name.
",anonymous
4,16,Mentioning a qualified identifer in doc loses the qualifier,,defect,2008-06-19T23:49:51Z+0100,2009-01-20T13:03:19Z+0000,"Mentioning a qualified identifer in doc loses the qualifier, even when it is required?  (see ""[Haskell] auto-qualification of identifiers in Haddock"").
",waern
4,17,A module re-export should only reference the target module if all of it is imported,,defect,2008-06-19T23:53:44Z+0100,2008-06-19T23:53:44Z+0100,"A module re-export should only reference the target module if the target module is imported without hiding any of its exports (otherwise we should inline just the exported bits).
",waern
4,21,Add some way to refer explicitly to either a type/class constructor or a data constructor,,enhancement,2008-06-25T13:01:14Z+0100,2008-12-23T13:21:13Z+0000,There's no way to refer explicitly to either a type/class constructor or data constructor when there are more than one of these with the same name.  Perhaps introduce a special syntax for them?  (eg. ':C' means data constructor C?),waern
4,22,Optionally show qualifications of identifiers,,enhancement,2008-06-25T13:08:33Z+0100,2012-03-31T18:11:31Z+0100,"Optionally show qualifications of identifiers, that is print ""Sequence.map"" rather than ""map"", ""Music.T"" rather than just ""T"". The option for haddock could be
{{{
    --qualification QUAL
          QUAL=none   (default) strip off qualification (just ""map"")
          QUAL=orig   show the identifiers as they are written in the module (e.g. ""map"" or ""List.map"")
          QUAL=full   show all identifiers with full qualification (Data.List.map)
}}}

Actually I tried to implement it by myself in the old Haddock, but I could not precisely identify the place, where the qualification is removed.",anonymous
4,23,Documentation of arguments of type constructors other than 'top level' arrows,,enhancement,2008-06-25T13:18:13Z+0100,2009-01-20T13:00:32Z+0000,"Documentation of arguments of type constructors other than 'top level' arrows. E.g.

{{{
   T (a {- ^ arg -}  ->  b {- ^ result -} )
   (a {- ^ arg -}  ->  b {- ^ result -} ) -> c
   (a {- ^ x coord -}, b {- ^ y coord -}) -> c
}}}

It's probably difficult to format properly in HTML.",waern
4,25,Indicate changed between versions in the documentation,,enhancement,2008-06-25T13:31:57Z+0100,2009-01-20T13:05:14Z+0000,"Haddock could compare interfaces from multiple versions of a module and indicate changes between versions (eg. a small ""new!"" or ""changed!"" icon, or ""stable since 1.0"").",waern
4,26,Something equivalent to JavaDoc's @since,,enhancement,2008-06-25T13:32:29Z+0100,2008-06-25T13:32:29Z+0100,Something equivalent to JavaDoc's @since.,waern
4,27,Nested itemized and enumerated lists,,enhancement,2008-06-25T14:37:30Z+0100,2012-10-14T01:22:01Z+0100,Nested itemized and enumerated lists.,waern
4,28,"Support structure (section headings, etc) in the description and possibly in other comments",,enhancement,2008-06-27T11:43:05Z+0100,2008-06-27T11:43:05Z+0100,"There ought to be a way to include some structure in the ""description"" (section headings, etc.) and possibly in other comments. (suggested by Daan).",waern
4,30,Comments on default method declarations,,enhancement,2008-06-27T11:44:32Z+0100,2008-12-23T16:06:04Z+0000,suggested by Satnam.,waern
4,31,"Comments on components of a tuple, for argument or return types.",,enhancement,2008-06-27T11:45:07Z+0100,2009-01-20T13:01:24Z+0000,,waern
4,32,Allow documentation annotations to explicitly name the entity they refer to,,enhancement,2008-06-27T11:48:22Z+0100,2008-06-27T11:48:22Z+0100,,waern
4,33,"In the contents page, indicate portability/stability of each module somehow",,enhancement,2008-06-27T11:49:11Z+0100,2008-06-27T11:49:11Z+0100,,waern
4,34,Add back-references from the definition to the uses of types/classes,,enhancement,2008-06-27T11:51:11Z+0100,2008-06-27T11:51:11Z+0100,Add back-references from the definition to the uses of types/classes (perhaps in the index?).,waern
4,35,Show fixities in the documentation,,enhancement,2008-06-27T11:52:38Z+0100,2008-11-06T00:04:45Z+0000,,waern
4,36,Include file revision info in module headers,,enhancement,2008-06-27T11:53:04Z+0100,2008-06-27T11:53:04Z+0100,,waern
4,39,Allow more parts of the documentation to be squashed and expanded,,enhancement,2008-06-27T11:57:19Z+0100,2008-06-27T11:57:19Z+0100,,waern
4,40,"For a constructor, don't fill its entire cell with a grey background.",,enhancement,2008-06-27T11:57:44Z+0100,2008-06-27T11:57:44Z+0100,,waern
4,41,Perhaps switch to longer rendering form for datatypes when necessary,,enhancement,2008-06-27T11:58:32Z+0100,2008-06-27T11:58:32Z+0100,,waern
4,42,Remove extra whitespace from the generated HTML to save space,,enhancement,2008-06-27T11:59:00Z+0100,2008-06-27T11:59:00Z+0100,,waern
3,43,Comments on GADT constructors,None,enhancement,2008-06-28T22:32:37Z+0100,2012-10-10T21:06:34Z+0100,"eg. this fails:

data I ev w a where
    Returns :: a -> I ev w a
    Binds :: I ev w a -> (a -> I ev w b) -> I ev w b
    Gets :: Ord ev => Maybe ev -> Maybe ev -> I ev w ev 
    -- ^ Accept any character between given bounds. Bound is ignored if @Nothing@.
",jeanphilippe.bernardy@…
4,54,how to handle packages with add-on instances?,,enhancement,2008-08-23T14:40:17Z+0100,2011-12-16T03:54:39Z+0000,"currently, haddock records instances with their class and their data type.

But what if I have a package that adds instances for classes and data types from other packages? In principle, haddock/cabal should update the existing pages, but I don't think they do, so my instances remain undocumented.

Alternative: store instances in separate xml file, have haddock pages for data/class extract and present the relevant instances from that xml file. That way, only the instances data base file needs to be updated, the other pages always present the latest state.

It might also be useful to present instances in the modules that define and reexport them, to document where instances are coming from and what instances will leak into your code by importing a module. This should probably be separate from the main module doc page hierarchy, in a separate instance import/export relation view.",claus
4,60,Parser fails on same-line documentation,,defect,2008-10-08T10:06:30Z+0100,2009-03-01T13:09:55Z+0000,"{{{
data Empty -- ^ This datatype has no elements
}}}

gives a Haddock parse error.

These two options fix it, but both seem like they should be unnecessary:

{{{
data Empty; -- ^ This datatype has no elements
}}}

{{{
data Empty
-- ^ This datatype has no elements
}}}
",ryani
3,70,'Contents' improvements based on Python's docs,None,enhancement,2009-01-10T22:00:16Z+0000,2012-09-25T12:09:55Z+0100,"Contrasting this page: http://haskell.org/ghc/docs/latest/html/libraries/

With this one: http://docs.python.org/library/index.html

We can see a number of ways to improve the library listings for haddock contents.

First, there descriptions given to the libraries, rather than just their names.

Second, the libraries themselves are grouped into type groups, above and beyond the lib paths themselves.

Third, when you actually drill into a page a 'breadcrumb' is placed at the top of the page for navigating back out. Example, clicking on 'array' yields a page headed with:
  Python v2.6.1 documentation » The Python Standard Library » Data Types »

These are 3 links, each stepping back up to a different containing level.",crutcher@…
4,71,Derive portability information from pragmas,None,enhancement,2009-01-15T21:31:20Z+0000,2012-09-25T12:09:55Z+0100,"It's too easy to write wrong Portability information in the Portability field of a module's haddock header. I wish that Portability information is automatically derived from a LANGUAGE or OPTIONS_GHC pragma, e.g. when no Portability field is specified.
Somehow related to ticket #33.
",haddock@…
3,72,Wiki-like interface,,enhancement,2009-01-18T21:48:04Z+0000,2011-04-24T13:01:06Z+0100,"There have been various suggestions about adding a wiki-like interface to Haddock, to be able to quickly suggest improvements by editing documentation directly on the page.

The system could produce a darcs patch or diff against the current source of the documented module, based on the modification. This patch could be sent to e.g. the libraries@haskell.org list or to the maintainer of the package.

Some people have suggested that it should be possible to directly update the documentation (but not the source), with an option for viewing the current or source-based docs.

Several extensions to this can be imagined:
  - comments on other peoples comments/modifications (reddit[1]/forum-style)
  - ranking of modifications/comments (reddit-style)

The benefit of reddit-like commenting is that a suggested modification can be discussed and improved by other users reading the same doc, without having to subscribe to a mailing list. This would probably generate more discussions and more participants in discussions. For some packages, a @libraries discussion is of course always needed in the end.

Please use this ticket for discussing the design and implementation of these features! To begin with, we could discuss how to just implement a wiki-like way of editing the documentation to produce a patch.

We should also look at other similar system. One of them is Annotated CPAN [2].

[1] http://www.reddit.com/

[2] http://www.annocpan.org/",waern
5,73,file name does not match module name `Main',None,defect,2009-01-23T18:04:33Z+0000,2012-09-25T12:09:54Z+0100,"At least an orthografical error: dependency graph.

Furthermore, i don't understand the error: why haddock has to create a dependency graph?",anonymous
3,79,Source links don't work for things defined using Template Haskell,None,defect,2009-02-04T22:47:31Z+0000,2012-09-25T12:09:54Z+0100,The reason for this is that HsColour can't insert anchors for TH declarations. Perhaps TH defs could be linked by line number somehow? (This would obviously need to be coordinated with HsColour.),SamB
3,80,No way to express docstrings in Template Haskell,None,defect,2009-02-04T22:55:14Z+0000,2012-09-25T12:09:54Z+0100,"It's annoying that you can't create boilerplate docstrings in Template Haskell. It would be really handy for e.g. Derive's pseudo-derivations ""Update"" and ""Is"".",SamB
4,82,Comments inside record field types,None,enhancement,2009-02-06T23:41:26Z+0000,2012-09-25T12:09:54Z+0100,"for some reason,

{{{
newtype P a = P { runP ::
                        String          -- ^ Input string
                     -> Int             -- ^ Current column
                     -> Int             -- ^ Current line
                     -> SrcLoc          -- ^ Location of last token read
                     -> ParseState      -- ^ Layout info.
                     -> ParseMode       -- ^ Parse parameters
                     -> ParseStatus a
                }
}}}
fails to parse, but
{{{
newtype P a = P { runP ::
                        String          -- Input string
                     -> Int             -- Current column
                     -> Int             -- Current line
                     -> SrcLoc          -- Location of last token read
                     -> ParseState      -- Layout info.
                     -> ParseMode       -- Parse parameters
                     -> ParseStatus a
                }
}}}
parses fine.",SamB
3,83,Better parse error messages when parsing the contents of Haddock comments,None,enhancement,2009-02-07T10:46:27Z+0000,2012-09-25T12:09:55Z+0100,Needs to be done in GHC.,waern
4,84,Document << picure-URL >> syntax,None,defect,2009-02-07T10:59:10Z+0000,2012-09-25T12:09:55Z+0100,,waern
4,85,show kind signatures for (gadt) type constructors,,enhancement,2009-02-09T05:41:24Z+0000,2010-11-23T22:48:36Z+0000,"I like to write GADT declarations in the following style:
{{{
{-# LANGUAGE GADTs, KindSignatures #-}
data Foo :: (* -> *) -> * -> * where
  Bar :: f x -> Foo f (f x)
}}}
so I don't give (necessarily unused) names to the type parameters of the type constructor `Foo`.  If I don't export the data constructors of `Foo` but only `Foo` itself then the documentation generated by Haddock consists solely of
{{{
data Foo
}}}

This is uninformative and potentially misleading (it seems to suggest that `Foo` has kind `*`).  It would be better to produce
{{{
data Foo :: (* -> *) -> * -> *
}}}


This is a particularly bad set of circumstances (no constructors for the reader to infer the kind from) but in general I think it would be nice to preserve any kind signatures written in the program source.",rwbarton@…
4,86,don't show leading foralls in type signatures,,enhancement,2009-02-09T06:11:52Z+0000,2011-12-16T03:55:31Z+0000,"When using `ScopedTypeVariables` it's necessary to write leading foralls in type signatures in order to scope free variables over the body of the function definition.  Haddock reproduces these explicit foralls in its output.  As I see it, whether a function definition is written with explicit foralls is an implementation detail--it doesn't affect users of the function, and in most cases the function could have been written without `ScopedTypeVariables`.  So I think Haddock's output ideally shouldn't include these leading foralls; they're distracting, especially when some but not all of the functions in a module have them.",rwbarton@…
4,88,Sections in the midst of algebraic datatype definitions,None,enhancement,2009-02-09T17:55:53Z+0000,2012-09-25T12:09:54Z+0100,"This would be good for code like this:

{{{
data BinOp
    = Add
    | Sub

    | Mul
    | Mulx
    | UMulx

    | Div   -- ^ round to -Infinity
    | Mod   -- ^ mod rounding to -Infinity

    | Quot  -- ^ round to 0
    | Rem   -- ^ rem rounding to 0

    | UDiv  -- ^ round to zero (unsigned)
    | UMod  -- ^ unsigned mod

    -- bitwise
    | And
    | Or
    | Xor
    | Shl
    | Shr    -- ^ shift right logical
    | Shra   -- ^ shift right arithmetic
    | Rotl
    | Rotr
    -- floating
    | FAdd
    | FSub
    | FDiv
    | FMul
    | FPwr
    | FAtan2

...
}}}
",SamB
3,89,character references are not recognized in emphasized text,2.13.2,defect,2009-02-12T21:00:05Z+0000,2012-10-14T20:08:57Z+0100,"If I write {{{/Hello&#A0;world!/}}} in a doc string, I don’t get a non-breaking space between “Hello” and “world!” in the output but I get “&#A0;” instead.",g9ks157k@…
4,91,Complexity annotations,None,enhancement,2009-02-21T00:21:58Z+0000,2012-09-25T12:09:54Z+0100,"It would be nice to be able to annotate certain functions with their time (maybe even space, if appropriate) complexity, and to have it appear in a distinctive place in the generated HTML. Currently some libraries write it at the beginning of the textual documentation of each function, which works, but it would be nice to have a more structured approach to this.",pumpkingod@…
4,92,Source links not aligned properly in Google Chrome,None,defect,2009-02-25T16:04:58Z+0000,2012-09-25T12:09:55Z+0100,,waern
3,94,Give a useful warning message instead of a cryptic parse error when encountering unexpected Haddock comments,_|_,enhancement,2009-03-01T12:13:29Z+0000,2012-03-10T00:22:08Z+0000,"See this failure when processing XMonad:
{{{
XMonad/Layout.hs:55:19: parse error on input `!' haddock: Failed to check module: XMonad.Layout

The relevant lines:

data Tall a = Tall !Int -- ^ The default number of windows in the master pane (default: 1)
                   !Rational -- ^ Default proportion of screen occupied by master pane (default: 1/2)
                   !Rational; -- ^ Percent of screen to increment by when resizing panes (default: 3/100)
}}}

Since we don't support Haddock comments on individual arguments of constructors, this just fails with a parse error. Perhaps we should give a warning message instead. In general, it would be good if we give a warning message instead of a parse error whenever a Haddock comment is encountered where it is not expected.

I think implementing this is hard, given the way things currently work. Haddock comments are just ordinary tokens that are fed to the parser in GHC, and we clearly don't want put them all over the grammar. If we should move to a design where Haddock comments are not in the grammar, but are collected elsewhere, implementing this ticket would be easier.",waern
4,95,Haddock comments on constructor arguments,,enhancement,2009-03-01T12:35:29Z+0000,2013-02-18T13:03:54Z+0000,"We could try to support Haddock comments on individual constructor arguments:

{{{
data A = A Int   -- ^ Documentation for the Int argument
           Float -- ^ Documentation for the Float argument
       | B
}}}

But I'm not sure how, since we already support commenting constructors on the same line:

{{{
data T a b
  = C1 a b  -- ^ This is the documentation for the 'C1' constructor
  | C2 a b  -- ^ This is the documentation for the 'C2' constructor
}}}

Perhaps we could require a parenthesis around the last argument?

{{{
data A = A Int   -- ^ Documentation for the Int argument
           (Float -- ^ Documentation for the Float argument)
       | B
}}}

Or around both arguments, for consistency:

{{{
data A = A (Int   -- ^ Documentation for the Int argument)
           (Float -- ^ Documentation for the Float argument)
       | B
}}}",waern
3,97,Reusable named chunks of documentation for declarations,None,enhancement,2009-03-09T14:52:44Z+0000,2012-09-25T12:09:54Z+0100,"Currently there is no way of using the same piece of Haddock documentation for two different declarations, apart from copying and pasting it, which can easily lead to them falling out of sync. The current `-- $` syntax only works for documentation which is not attached to declarations.

Support for this is useful in cases where you have two or more functions which essentially implement a common interface that hasn't been made into a type class. Examples are `Data.ByteString` versus `Data.ByteString.Lazy` or `Data.Map` versus `Data.IntMap`: looking at the docs of `bytestring-0.9.1.4` I see that `Data.ByteString.Lazy.intersperse` doesn't say that it's `O(n)`, but `Data.ByteString.intersperse` does—an obvious omission. There should be a mechanism for avoiding these kinds of errors, which tend to become worse over time.

Extending the `-- $` syntax makes the most sense to me. It could be possible to write something like the following, taking `append` from `bytestring` as an example:

{{{
module Data.ByteString (...) where
...

-- | @O(n)@ $append
...
}}}
{{{
module Data.ByteString.Lazy (...) where
...

-- | @O(n/c)@ $append
...
}}}
{{{
-- $append
-- Append two ByteStrings.
}}}

One thing that isn't obvious to me: should the definitions of the chunks have to be in the same module, like now, thus essentially forcing CPP usage? Or would an import be okay? That could lead to ambiguity—should the normal Haskell disambiguation syntax (`Module.foo`) be allowed, then? That could make this ridiculously complex; CPP seems the simplest solution but it's arguably not very clean. Either way would satisfy me.",Deewiant
3,101,haddock-2.4.2 shipped with ghc-6.10.2 is extremely slow,None,defect,2009-04-21T12:49:02Z+0100,2012-09-25T12:09:54Z+0100,"Calling haddock for our Hets project http://www.dfki.de/sks/hets takes around 40 minutes after upgrading to ghc-6.10.2. (haddock 2.3.0 with ghc-6.10.1 took below 1 minute.)

Unfortunately, reproducing this behavior requires to install many packages. You need fgl, xml, and time to compile anything at all within Hets. 

Check out:
https://svn-agbkb.informatik.uni-bremen.de/Hets/trunk
https://svn-agbkb.informatik.uni-bremen.de/uni/trunk

You need the uni packages and hxtfilter-8.2.0 to cause haddock to become slow.
(Look inside `Hets/INSTALL`)

Within Hets I call:
{{{
cabal configure -v -f -gtkglade -f -programatica -f -shellac -f -haxml -f -tabular -f -tar
}}}
to avoid dependencies on even further packages.

Compiling 433 files using ""`time cabal build`"" takes:

{{{
real    4m34.159s
user    4m21.308s
sys     0m7.456s
}}}

Running now haddock using ""`time cabal haddock --executables`"" takes about 40 minutes

I'll attach the corresponding log files. (The sources contain one template haskell file 
`Hets/SoftFOL/MathServCommunication.hs`)



 ",maeder
4,110,Allow grouping of functions with a corresponding data type,,defect,2009-06-21T22:47:55Z+0100,2009-06-21T22:58:04Z+0100,"Suppose you're refactoring to use smart constructors. So you switch from exporting:

{{{
data WindowBits
 = WindowBits Int
 | DefaultWindowBits
}}}
to:
{{{
data WindowBits

defaultWindowBits :: WindowBits

windowBits :: Int -> WindowBits
}}}

Currently the former is presented with a more logical grouping than the latter. In the constructor case we get the docs for the whole lot all in one block which clearly indicates that they are related. With the latter, each smart constructor is just an independent top level function and only the order makes them look in any way related (obviously the names and types make them look related, but the structure and presentation does not).

So what I'd like is a way to group related top level exports, so that when there is a very strong relation, such as in the smart constructor case, I can indicate that in the markup and have it presented nicer.

Currently there is a disincentive to switch from constructors to smart constructors because it makes the API look bigger and less organised. This is a bit of a shame.

The obvious question is how should the grouping be indicated and how should it affect the default presentation.",duncan
3,114,Make the frames version a separate output mode,None,enhancement,2009-07-07T10:07:54Z+0100,2012-09-25T12:09:54Z+0100,"The frames version of the html haddock output is almost universally ignored. That is the files:
{{{
frames.html
index-frames.html
mini_$MODULE.html
}}}
which are generated to support the frames view.

Since nobody uses the frames view and it takes extra space and clutter, how about making it a separate mode.

{{{
--html         output in HTML
--html-frames  output in HTML using frames
}}}

Note: when extracting the frames code from the normal code, make sure to omit the on-load code from the html head:
{{{
<SCRIPT TYPE=""text/javascript"">
window.onload = function () {
  setSynopsis(""mini_Distribution-Simple.html"")
};
</SCRIPT>
}}}",duncan
3,115,allow putting support files in a relative subdir,None,enhancement,2009-07-07T10:17:22Z+0100,2012-09-25T12:09:54Z+0100,"We're adding support in Cabal to maintain an index of all docs installed on the system. The only problem is that we are cluttering the directory with lots of other haddock support files.
http://hackage.haskell.org/trac/hackage/ticket/516#comment:1

In the cabal config file we say
{{{
doc-index-file: $datadir/doc/index.html
}}}
but of course when we call haddock to make the index it generates a bunch of other files in the same directory. This is rather annoying in this use case. Yes we could have the default be something like:
{{{
doc-index-file: $datadir/doc/haddock-index/index.html
}}}
but since `$datadir/doc/` really is the top of the doc tree then it's nice to have the index live there.

What would be ideal is if we could put the index.html file at the top but direct that the support files (css, gif, js) go into a subdirectory relative to the target.

Specifically I'm suggesting something like:
{{{
--support-odir=haddock-util
}}}
which would then dump the support files into the `$odir/haddock-util`. The references in the generated html would obviously have to use that relative path to the support files.

This along with being able to suppress the frames output (#114) would make the Cabal haddock index more or less ideal.",duncan
4,117,"Data constructors printed prefix, when symbolic (begin-with-a-colon), should be parenthesized",,defect,2009-07-20T17:11:00Z+0100,2009-07-20T17:11:00Z+0100,"for example,
{{{
data Foo = (:::) Int Bool
}}}
is displayed by Haddock similarly except without the parentheses.  Obviously it should use the parentheses anytime it's not using such a thing infix-ly.",isaacdupree
4,121,"Support export of modules using their ""as"" name",None,defect,2009-11-04T06:36:31Z+0000,2012-09-25T12:09:54Z+0100,"Haskell allows you to import modules using an ""as"" name, and re-export the module using that name:
  
   module Language.Python.Common ( module Pretty )
   import Language.Python.Common.Pretty as Pretty

It seems that Haddock 2.4.2 has trouble with this and complains that:

   Warning: language-python-0.2:Language.Python.Common: Could not find documentation for exported module: Pretty

Changing the export to use the full qualified name of the module fixes the problem.",bjpop
4,122,two URLs on one line will be parsed as one long URL with >< characters in,None,defect,2009-11-11T06:35:47Z+0000,2012-09-25T12:09:54Z+0100,"Simple bug, if there's a haddock comment like

    -- | <http://example.com> blah blah <http://dmwit.com>

it will be rendered as one long link to the URL ""http://example.com> blah blah <http://dmwit.com"", rather than as separate URLs.",dmwit
4,123,Comments on instance methods,,enhancement,2009-11-24T22:32:22Z+0000,2011-12-16T03:56:20Z+0000,We need a more detailed view of instances before we implement this.,waern
4,124,Auto-generated comments on derived/TH-generated instances,,enhancement,2009-11-24T22:41:54Z+0000,2009-11-24T22:41:54Z+0000,"Ross suggested generating comments on derived instances so that the user can figure out what they mean. It would be good if we could also:
  * generate comments on template-haskell-generated instances
  * distinguish derived instances from template-haskell generated instances somehow",waern
4,125,Use nice unicode symbols for keywords,None,enhancement,2009-12-10T09:40:07Z+0000,2012-09-25T12:09:54Z+0100,"When I have this in my source:

{{{
runDeviceRegionT ∷ MonadCatchIO pr ⇒ (∀ s. DeviceRegionT s pr α) → pr α
}}}

It is rendered to this:

{{{
runDeviceRegionT :: MonadCatchIO pr => (forall s. DeviceRegionT s pr α) -> pr α
}}}

So all the nice unicode symbol keywords are rendered as their ASCII equivalents.

It would be nice if the nice unicode symbols were kept intact.

There seems to me three approaches we can take:

 * Status-quo: All keywords will always be shown in ASCII regardless of their potential nice unicode symbol source.
 * Have an option to only show nice unicode symbols for only those keywords that have a unicode symbol source.
 * Have an option to always show nice unicode symbols for all keywords regardless of their potential ASCII or nice unicode symbol source.

",basvandijk
4,126,multi-line emphasis not working,,defect,2009-12-23T11:00:51Z+0000,2009-12-23T11:05:37Z+0000,I discovered that there is a test for multi-line emphasis that currently passes but the text is not emphasized. Needs to be investigated.,waern
4,129,Missing parenthesis around infix GADT constructors,,defect,2010-01-26T15:04:12Z+0000,2010-03-31T18:44:05Z+0100,"Here's an example:

http://hackage.haskell.org/packages/archive/operational/0.1.0.0/doc/html/Control-Monad-Operational.html#v%3A%3A%3E%3E%3D",waern
3,130,Better handling of links to cross-package documentation,,enhancement,2010-01-28T23:26:36Z+0000,2010-03-31T18:40:04Z+0100,"Currently, when linking to something that is exported by multiple packages, how do we choose which package to link to? The answer is that this is determined by the order of the --read-interface flags passed to Haddock. And it works this way mostly by accident.

I think it would be better to automatically try to find the ""best"" package to link to, just like we do for modules. And I think we should follow a similar rule to the one we use for modules and try to choose the package that is closest (or equal) to the original package. There are of course some more details that we need to sort out.
",waern
4,134,Hyperlink identifiers in examples and code blocks,,enhancement,2010-04-06T22:01:06Z+0100,2011-12-16T03:56:35Z+0000,,waern
3,138,Malformed or missing comments in files with #line directive,None,defect,2010-07-08T04:56:19Z+0100,2012-09-25T12:09:54Z+0100,"Using an example file with #line directives:

{{{
module Test(Data(..), func) where

#line 40 ""test.cpphs""
-- | data 'Data'
data Data = Data

#line 30 ""test.cpphs""
-- | Function 'func'

#line 20 ""test.cpphs""
func :: Data
func = Data
}}}

The documentation for {{{foo}}} will be rendered attached to {{{Data}}}. I feel this is incorrect, as {{{func :: Data}}} is the next line after {{{-- | Function 'func'}}}.

There's no 2.7.2 version available, so I'm leaving that field blank.",jmillikin
4,141,Hyperlinking does not work for =: or #!,,defect,2010-08-10T10:37:45Z+0100,2010-08-10T10:37:45Z+0100,"I'm writing a package which defines the infix operators `=:`, `#!` and `#!!`. However, I'm unable to generate hyperlinks to these operators. I have tried `'=:'`, `'#!'`, `'#!!'`, {{{`=:'}}}, `'(=:)'`, {{{`(=:)'}}}, `'Fully.Qualified.=:'` etc., but nothing seems to work.

I instead get the `'=:'` verbatim, with quotes included in the resulting HTML. Hyperlinking to all other operators, even operators also starting with = or #, seems to work just fine with the `'=:'` syntax.

I have tried this both in the module that defines the operator in question, and in an another module that imports that module. The hyperlinks aren't generated in either case.

I have tested this with both Haddock 2.6.1 (the one in the newest Haskell Platform) and Haddock 2.7.2 (the cabal-installable one), and the hyperlinks don't work with either.
",Astra
4,143,Multi-line emphasis not working,,defect,2010-08-28T17:20:31Z+0100,2010-08-28T17:20:31Z+0100,See {{{tests/golden-tests/tests/Bug3.hs}}}.,waern
3,144,Allow -- ^ comment on record constructor,None,enhancement,2010-09-01T17:12:37Z+0100,2012-09-25T12:09:54Z+0100,"This enhancement would add flexibility to the commenting style for record constructors.  Accept a `-- ^` comment between a constructor and its fields, meaning the same as a `-- |` comment before the constructor.  The example below is rejected as a parse error due to the comment on 'Branch'.

{{{
-- | A tree with labeled internal nodes
data Tree =
    Empty                -- ^ Leaf
  | Branch               -- ^ Internal node
    { label :: a         -- ^ Node label
    , subtrees :: [Tree] -- ^ List of subtrees
    }
}}}",heatsink
3,145,Type class instances: link to source,None,enhancement,2010-09-06T09:46:25Z+0100,2012-10-18T15:59:08Z+0100,Currently the detailed documentation of a type class lists known instances of the type class. It'd be really helpful if the instances linked to their source wherever possible.,MartijnVanSteenbergen
4,147,missing line breaks in functions types without comments,,defect,2010-09-06T22:56:47Z+0100,2010-09-07T03:05:12Z+0100,"if a function's type contains no embedded annotations,
then it is rendered without any reasonable linebreaks
(it just breaks at the right border) which makes it hard to read.

See function symdiff here
http://dfa.imn.htwk-leipzig.de/doc/autolib-fa-1.1/html/Autolib-NFA-Minus.html

and I attach a screenshot, just to be sure.
",JohannesWaldmann
4,148,synopsis tab is too wide (so that it cannot be closed),,defect,2010-09-06T23:01:02Z+0100,2010-11-30T03:17:03Z+0000,"if the functions's types contain long lines (see ticket #147),
then the synopsis tab is wider than the window,
so its control (for closing) is invisible.

",JohannesWaldmann
4,149,Long instance declarations are breaking layout.,None,defect,2010-09-07T11:23:18Z+0100,2012-09-25T12:09:54Z+0100,http://hackage.haskell.org/packages/archive/HList/0.2.3/doc/html/Data-HList-Record.html#t:Record,rkit
3,151,long lines in the synopsis,None,defect,2010-09-16T09:03:20Z+0100,2012-09-25T12:09:54Z+0100,"the synopsis widget looks bad for very long lines (which is bad style anyway).

e.g. http://hackage.haskell.org/packages/archive/gdiff/1.0/doc/html/Data-Generic-Diff.html#t:EditScriptL",bastl
3,154,Comments on associated types,None,enhancement,2010-10-03T22:16:01Z+0100,2012-09-25T12:09:55Z+0100,,waern
4,155,Infix constraints are printed prefixed,,enhancement,2010-10-04T21:52:55Z+0100,2011-05-24T13:34:50Z+0100,"In my `regions` package I make extensive use of infix constraints.

Take my [http://hackage.haskell.org/packages/archive/safer-file-handles/0.8/doc/html/System-IO-SaferFileHandles.html#8 hFileSize] function for example. If you look at the source you'll notice that the constraint: {{{pr `ParentOf` cr}}} is written infix. However haddock prints it prefixed: {{{ParentOf pr cr}}}.

It would be nice if Haddock respected the fixity of the written constraint.

",basvandijk
3,157,Push/improve Haddock API and .haddock files usage,None,defect,2010-11-04T16:28:42Z+0000,2012-09-25T12:09:54Z+0100,"I'd expect Haddock processing to involve three stages:

  1. extract information for each file/package

  2. mix and match information batches for crosslinking

  3. generate output for each file/package

where the results of 1 should be available `.haddock` files, so that stage 2/3 tools can start from there if source isn't available, and the results of 2 should be exposed in the API, so that it can be shared between backends.

Currently, backends such as `--hoogle` can't start from `.haddock` files, and stage 2 processing is duplicated in what should be stage 3-only backends. It might also be useful to think about the representation of the output of stage 2 above: currently, Haddock directly generates indices in XHtml form, even though much of the index computation should be shareable accross backends. 

Relatedly, the Haddock executable should be a thin wrapper over the Haddock API, if only to test that the API exposes sufficient functionality for implementing everything Haddock can do.

Instead, there is an awful lot of useful code in Haddock's Main.hs, which is not available via the API. So when coding against the API, for instance, to extract information from .haddock files, one has to copy much of that code.

Also, some inportant functionality isn't exported (e.g., the standard form of constructing URLs), so it has to be copied and kept in synch with the in-Haddock version of the code.

Overall, it seems that exposing sufficient information in the API, and allowing `.haddock` interface files as first-class inputs, there should be less need for hardcoding external tools into Haddock (such as --hoogle, or haddock-leksah). Instead, clients should be able to code alternative backends separately, using Haddock to extract information from sources into `.haddock` files, and the API for processing those `.haddock` files.

(splitting Haddock into frontend/indexer/backend would be better than similar documentation plugin functionality available, for instance, in [http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html Javadoc doclets], for alternate output formats.)

More documentation about the role and usage of these two Haddock features (API, `.haddock` files), as well as the plans for their development would also be useful.

Mailing list thread: http://www.haskell.org/pipermail/haskell-cafe/2010-October/085434.html",claus
3,158,Quasiquotation breaks Haddock/GHCi,None,defect,2010-11-10T23:11:19Z+0000,2012-09-25T12:09:54Z+0100,"When trying to generate Haddock documentation for any file that uses [http://www.haskell.org/haskellwiki/Quasiquotation quasiquotation], I get an error message similar to this:

{{{
% haddock -o doc -h Main.hs         

During interactive linking, GHCi couldn't find the following symbol:
  Quasi_qq_closure
This may be due to you not asking GHCi to load extra object files,
archives or DLLs needed by your current session.  Restart GHCi, specifying
the missing library using the -L/path/to/object/dir and -lmissinglibname
flags, or simply by naming the relevant files on the GHCi command line.
Alternatively, this link failure might indicate a bug in GHCi.
If you suspect the latter, please send a bug report to:
  glasgow-haskell-bugs@haskell.org
}}}

GHCi loads the modules fine when invoked manually. I'm using Haddock 2.8.1 and GHC 6.12.3 on OS X 10.6.4. I've attached a trivial quasiquoter (Quasi.hs) and Main.hs which uses it and causes problems for Haddock.",arcatan
3,160,LaTeX output improvements,None,enhancement,2010-11-19T10:38:41Z+0000,2012-09-25T12:09:55Z+0100,"I tried to use LaTeX output and it seems as a good step forward. But there are still some rough edges. Here are some suggestions:

 * decouple main tex file with one more include so that it is possible to include whole package into another tex file, together with prologue, so one file with prologue and list of all sub-modules, and another which wraps it up and creates full document
 * allow to specify page width, currently even if I use landscape page orientation and wider page types and module exports are still wrapped at original (internal) page width
 * using `article` class does not seem to work without errors, together with that it would be useful to be able to disable empty pages
 * wrapping of function types into multiple lines is strange and consumes too much lines, wouldn't it be better that types are normally wrapped at the end of the line and not that it is tried to wrap them at the beginning (thus using only one type per line until the rest comes into whole line)
 * the same goes for export list, sometimes it just wraps into multiple, multiple lines, maybe changing this into normal tabular format (everything after `::` is just a tabular cell) will also remove requirement to hard-code page width (suggestion above), so that whole text positioning would be done by LaTeX and not preprocessed (this is especially important when you want to include LaTeX output into some other document, like appendix for example)
 * support for same style as lhs2TeX (using special characters to represent '::', '->' and others)",mitar
3,161,Nested {- -} comments in code examples,None,defect,2010-11-28T00:22:36Z+0000,2012-09-25T12:09:54Z+0100,"This...

{{{
-- > {- long comment -}
}}}

...get's printed out in the haddock document just as you'd expect it to, but...

{{{
{-

> {- long comment -}

-}
}}}

...is not shown at all.

See for example http://n-sch.de/hdocs/test/Test.html",McManiaC
3,162,Unable to use single quote immediately after hyperlinked identifiers,None,defect,2010-11-30T03:12:47Z+0000,2012-10-18T07:31:03Z+0100,"I am unable to use single quote immediately after hyperlinked identifiers, for example I would like to do write:

{{{
'Element'\'s
}}}

and I get in HTML rendered exactly the same thing back instead of `Element` being hyperlinked and `'s` printed after the link.",mitar
3,164,Hyperlinked identifiers are not made for identifiers from other exported modules,None,defect,2010-11-30T04:48:22Z+0000,2012-09-25T12:09:55Z+0100,"If I have multiple modules and export them in the one public module I cannot make hyperlinked identifiers between them in documentation. But this looks strange as the user sees only one module with documentation where same identifiers are linked and some are not in the same module. The problem is that internal modules cannot import other modules because of the import cycles so that those identifiers would be visible. So this cannot be easily solved in Haskell code, but as haddock supports exported modules it should take care that it searches for identifiers in the module documentation is visible and not (just) where it is defined.",mitar
4,165,Parse error on comment before opening brace of record,None,defect,2010-12-12T19:06:43Z+0000,2012-09-25T12:09:55Z+0100,"This gives ""parse error on input `{'"":
{{{
data Test =
    Test
        -- | A value
        { a :: Int
        -- | Another value
        , b :: Int
        }
}}}
This does not:

{{{
data Test =
    Test
        { -- | A value
          a :: Int
        , -- | Another value
          b :: Int
        }
}}}
The first should parse and give the same result as the second.",Mathnerd314
3,166,Missing identifier in Haddock,None,defect,2010-12-16T21:31:17Z+0000,2012-09-25T12:09:54Z+0100,"In the llvm package the identifier 'constOf' is not shown, although it is exported and has a signature.
It makes the library users believe that the identifier does not exist or is not exported.
In the index it appears but it is not linked to the exporting module.
http://hackage.haskell.org/packages/archive/llvm/0.9.0.1/doc/html/doc-index-C.html
",Lemming
3,168,Errors in --hoogle output,None,defect,2010-12-22T22:45:43Z+0000,2012-09-25T12:09:54Z+0100,"Given the input file below, when running {{{haddock --hoogle Haddock.hs}}} I get the output below. There are 3 obvious bugs, all of which I think were introduced when rewriting various bits to move to using the GHC library (there was a bug number 3, which got fixed in Haddock 2.8).

I'm also tracking this bug at: http://code.google.com/p/ndmitchell/issues/detail?id=390

{{{
{-# LANGUAGE TypeOperators, IncoherentInstances #-}

module Haddock where


-- | BUG 1: bug1 will not have any documentation
class  BUG1 a  where
    -- | This documentation is dropped
    bug1 :: Integer -> a


data a :**: b = Bug2 -- ^ BUG 2: The :**: is prefix without brackets


-- | BUG 4: The instance below has [incoherent] on it
bug4 :: (); bug4 = ()
instance Num ()
}}}

{{{

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

@package main

module Haddock

-- | BUG 1: bug1 will not have any documentation
class BUG1 a
bug1 :: BUG1 a => Integer -> a
data (:**:) a b

-- | BUG 2: The :**: is prefix without brackets
Bug2 :: :**: a b

-- | BUG 4: The instance below has [incoherent] on it
bug4 :: ()
instance [incoherent] Num ()
}}}",NeilMitchell
4,170,The synopsis box can become too wide,,defect,2011-02-16T21:38:52Z+0000,2011-02-16T21:38:52Z+0000,"The new Synopsis box in the API docs expands beyond the monitor for
functions that have long signatures. An example is the TreeView
documentation  [1] in the gtk package.

I have only tested Firefox.

-deech

[1] http://hackage.haskell.org/packages/archive/gtk/0.12.0/doc/html/Graphics-UI-Gtk-ModelView-TreeView.html
",waern
3,171,haddock fails to parse {- # ... #-} (note the space) pragma,None,defect,2011-03-15T21:02:19Z+0000,2012-09-25T12:09:55Z+0100,"The problem was found on xmonad-0.9.2 haddock failure.

Minimal complete test looks as such:

{{{
$ haddock Fail.hs 

Fail.hs:1:3: parse error on input `#'
$ cat Fail.hs
{- # OPTIONS_GHC -fglasgow-exts    #-}

module Fail where
}}}

Reproducible with haddock-2.7.2 and 2.9.2.",slyfox
3,174,Haddock should hide hidden fields of re-exported modules,None,defect,2011-04-11T13:18:26Z+0100,2012-09-25T12:09:54Z+0100,"Suppose I have the following module:

{{{
module Compiler.Hoopl
  ( module Compiler.Hoopl.Graph
  , module Compiler.Hoopl.MkGraph
  , module Compiler.Hoopl.XUtil
  , module Compiler.Hoopl.Collections
  , module Compiler.Hoopl.Checkpoint
  , module Compiler.Hoopl.Dataflow
  , module Compiler.Hoopl.Label
  , module Compiler.Hoopl.Pointed
  , module Compiler.Hoopl.Combinators
  , module Compiler.Hoopl.Fuel
  , module Compiler.Hoopl.Unique
  , module Compiler.Hoopl.Util
  , module Compiler.Hoopl.Debug
  , module Compiler.Hoopl.Show
  )
where

import Compiler.Hoopl.Checkpoint
import Compiler.Hoopl.Collections
import Compiler.Hoopl.Combinators
import Compiler.Hoopl.Dataflow hiding ( wrapFR, wrapFR2, wrapBR, wrapBR2
                                      )
import Compiler.Hoopl.Debug
import Compiler.Hoopl.Fuel hiding (withFuel, getFuel, setFuel, FuelMonadT)
import Compiler.Hoopl.Graph hiding 
   ( Body
   , BCat, BHead, BTail, BClosed -- OK to expose BFirst, BMiddle, BLast
   )
import Compiler.Hoopl.Graph (Body)
import Compiler.Hoopl.Label hiding (uniqueToLbl, lblToUnique)
import Compiler.Hoopl.MkGraph
import Compiler.Hoopl.Pointed
import Compiler.Hoopl.Show
import Compiler.Hoopl.Util
import Compiler.Hoopl.Unique hiding (uniqueToInt)
import Compiler.Hoopl.XUtil
}}}

Haddock will incorrectly generate documentation for all functions in these modules, where it should actually hide any of the functions/data constructors that were hidden in the imports.",ezyang
4,178,Haddock 2.4.2 fails to parse TemplateHaskell modules on x86_64 due to recent binutils,None,defect,2011-08-17T04:29:05Z+0100,2012-09-25T12:09:54Z+0100,"I know this is a relatively old version, but it's what's packaged with GHC 6.10. I figure it's worth releasing a ...1 on Hackage, if nothing else.

Ticket #5050 describes how `-fvia-C` generates invalid assembly on x86_64, which is caught and refused by recent versions of binutils. The workaround is to not use `-fvia-C`.

Haddock 2.4.2 is hard-coded to use `-fvia-C` if the `TemplateHaskell` language extension is enabled. This prevents TH-enabled packages from having their documentation generated:

{{{
-- th_error.hs
{-# LANGUAGE TemplateHaskell #-}
module Main (main) where

main :: IO ()
main = return ()
}}}

{{{
$ /opt/ghc-6.10.4/bin/haddock th_error.hs 
/tmp/ghc18204_0/ghc18204_0.s: Assembler messages:

/tmp/ghc18204_0/ghc18204_0.s:160:0:
     Error: .size expression for Main_main_entry does not evaluate to a constant

/tmp/ghc18204_0/ghc18204_0.s:160:0:
     Error: .size expression for ZCMain_main_entry does not evaluate to a constant
}}}

This error can be solved by patching Haddock to use the equivalent of `-fasm`:

{{{
diff -ur haddock-2.4.2/src/Haddock/Interface.hs haddock-2.4.2.new//src/Haddock/Interface.hs
--- haddock-2.4.2/src/Haddock/Interface.hs	2009-03-21 12:22:17.000000000 -0700
+++ haddock-2.4.2.new//src/Haddock/Interface.hs	2011-08-16 20:25:31.551414886 -0700
@@ -97,9 +97,9 @@
   modgraph' <- if needsTemplateHaskell modgraph
        then do
          dflags <- getSessionDynFlags
-         setSessionDynFlags dflags { hscTarget = HscC } 
+         setSessionDynFlags dflags { hscTarget = HscAsm } 
          -- we need to set HscC on all the ModSummaries as well
-         let addHscC m = m { ms_hspp_opts = (ms_hspp_opts m) { hscTarget = HscC } }  
+         let addHscC m = m { ms_hspp_opts = (ms_hspp_opts m) { hscTarget = HscAsm } }  
          return (map addHscC modgraph)
        else return modgraph
 #else
}}}",JohnMillikin
4,179,Reusing named chunks in other modules,None,enhancement,2011-09-12T00:48:58Z+0100,2012-09-25T12:09:55Z+0100,"Similar to #97. Consider the following:

{{{
module A (
  -- $note
  f,
  )    
  where

  -- $note
  -- This is a long note.

  -- | This is a function
  f :: Int -> Int
  f x = x

module B (
  -- $A.note
  f,
 )
 where

  import A
}}}

Currently, there is no way to insert the documentation chunk named {{{$note}}} (which is defined in module {{{A}}}) into the documentation for {{{B}}}. I propose the above syntax as a way to do this.

The motivation for this construct is as follows. Since {{{A}}} and {{{B}}} export (at least some of) the same API, the {{{$note}}} chunk should be included in both of their Haddocks. It is possible to work around this need by using anchors to link to {{{A}}}'s note from {{{B}}}, but this a workaround rather than a solution.",reinerp
5,180,Should not “succeed” if all installed libraries’ interface files are of the wrong version,None,enhancement,2011-09-20T08:51:42Z+0100,2012-10-14T01:19:29Z+0100,"I find myself with two versions of Haddock installed: the Debian-supplied 2.9.2 in /usr/bin, and a cabal-install-provided 2.4.2 in ~/.cabal/bin, which is first in my $PATH. (Presumably this was due to some package depending on a newer version of Haddock than Debian provided in the distant past.)

As a result, when I install any package (with 'documentation: True' in my ~/.cabal/config), I receive warnings as follows:

{{{
Installing executable(s) in /tmp/hmph/bin
Updating documentation index /tmp/hmph/share/doc/index.html
Warning: Cannot read /usr/lib/ghc-doc/haddock/Cabal-1.10.2.0/Cabal.haddock:
   ""Interface file is of wrong version: /usr/lib/ghc-doc/haddock/Cabal-1.10.2.0/Cabal.haddock""
Skipping this interface.
Warning: Cannot read /usr/lib/ghc-doc/haddock/hunit-1.2.2.3/HUnit.haddock:
   ""Interface file is of wrong version: /usr/lib/ghc-doc/haddock/hunit-1.2.2.3/HUnit.haddock""
Skipping this interface.
... and so on, for every installed library
}}}

Since all of my installed libraries' .haddock files are of the wrong version, it might be nice if haddock failed, rather than succeeding but writing an [http://willthompson.co.uk/misc/empty-docs/ empty documentation index].",wjt
4,183,"""failed to parse haddock prologue from file"" error on module",None,defect,2011-10-21T00:13:39Z+0100,2012-09-25T12:09:55Z+0100,"I've attached the project-in-progress that gives me this error (please ignore the ugly code therein). I tried removing some of the blocks of comments to see if any of them were causing a parse error, but without luck.

{{{
» cabal configure && cabal haddock                                                    1 ↵
Resolving dependencies...
Configuring pez-0.1.0...
Running Haddock for pez-0.1.0...
Preprocessing library pez-0.1.0...
Warning: The documentation for the following packages are not installed. No
links will be generated to these packages: rts-1.0, fclabels-1.0.4
Warning: Cannot read /home/me/.cabal/share/doc/thrist-0.2/html/thrist.haddock:
   Interface file is of wrong version: /home/me/.cabal/share/doc/thrist-0.2/html/thrist.haddock
Skipping this interface.
haddock coverage for dist/build/tmp16310/Data/Label/Zipper.hs:   28/30  93%
Warning: Data.Label.Zipper: could not find link destinations for:
    Data.Label.Abstract.Lens Data.Label.Maybe.:~>
haddock: failed to parse haddock prologue from file: dist/doc/html/pez/haddock-prolog16310.txt
}}}

I am able to build documentation for some other modules on my disk, but this one craps out on me.


{{{
» whereis haddock
haddock: /usr/bin/haddock /usr/share/man/man1/haddock.1.gz
» whereis cabal
cabal: /usr/bin/cabal
» cabal --version
cabal-install version 0.10.2
using version 1.10.1.0 of the Cabal library 
» haddock --version
Haddock version 2.9.2, (c) Simon Marlow 2006
Ported to use the GHC API by David Waern 2006-2008
}}}

sorry to dump my whole project on you all, but I can't seem to get any helpful debugging messages or track down the source of the error.
",jberryman
3,185,Allow attaching new docs to functions that are re-exported,None,enhancement,2011-11-05T23:24:29Z+0000,2012-09-25T12:09:55Z+0100,"Use case:

We have `Data.Monoid` which exports `(<>)` with its associated documentation. We have a number of other modules that re-export the `(<>)` operator, such as `Text.Pretty`. These modules want to provide their own documentation for the `(<>)` operator.

Historically `Text.Pretty` defined `(<>)` locally so it was possible for it to give it documentation that makes sense in the context of `Text.Pretty`. Now that we have the `(<>)` defined in `Data.Monoid` and re-exported, that's no longer possible. Note that we do not want to define `(<>)` locally anymore, we really do want to re-export `Data.Monoid.<>`, we just want to give it more context sensitive documentation.

Note that this would be useful in other cases where some highly generic function is re-exported by a module dealing with a specific type. For example, suppose we changed `Data.List` to re-export `Data.Foldable.foldr`. We would not want to change the documentation of `foldr` in `Data.List`.

So how might this work?

The only place we could attach documentation would be in the export list, since that's the only place where we mention the function. So perhaps something like:

{{{
module Text.PrettyPrint.HughesPJ (
  ...
  -- ** Combining documents
  empty,
  -- | Beside.
  -- '<>' is associative, with identity 'empty'.
  (<>),
  (<+>), hcat, hsep,
  ...
)  where

import Data.Monoid ( Monoid(mempty, mappend), (<>) )

}}}

Presumably it also makes sense to allow $named doc chunks there too? I've never been quite sure of the syntax for that so I'm not sure if it'd add ambiguity.",duncan
3,187,"With TH, when doing ""cabal haddock"", GHCi ""couldn't find symbol""",None,defect,2011-11-13T08:57:37Z+0000,2012-09-25T12:09:55Z+0100,"This is a copy of the ticket http://hackage.haskell.org/trac/hackage/ticket/898, I've filed for Cabal. I include the whole ticket text below.

GHC 7.2.1, Cabal HEAD, Haddock 2.9.2. The message

{{{
During interactive linking, GHCi couldn't find the following symbol:
Allurezm0zi4zi2_UtilsziMultiline_multiline_closure
}}}

How to reproduce: get package http://hackage.haskell.org/package/Allure-0.4.2, cabal install, cabal haddock --executables and you should get the following:

{{{
Running Haddock for Allure-0.4.2...
Warning: The documentation for the following packages are not installed. No
links will be generated to these packages: ConfigFile-1.1.1, HUnit-1.2.4.2,
MissingH-1.1.1.0, ffi-1.0, rts-1.0, cairo-0.12.1, deepseq-1.1.0.2, gio-0.12.1,
glib-0.12.1, gtk-0.12.1, hslogger-1.1.5, mtl-2.0.1.0, network-2.3.0.6,
pango-0.12.1, parsec-3.1.2, random-1.0.1.0, regex-base-0.93.2,
regex-compat-0.95.1, regex-posix-0.95.1, text-0.11.1.6, transformers-0.2.2.0,
zlib-0.5.3.1
Preprocessing executable 'BotAllure' for Allure-0.4.2...
haddock coverage for dist/build/tmp-28531/src/Bot.hs:     0/3   0%
Warning: Main: could not find link destinations for:
    System.Random.StdGen
Documentation created: dist/doc/html/Allure/BotAllure/index.html
Preprocessing executable 'Allure' for Allure-0.4.2...
haddock coverage for dist/build/autogen/Paths_Allure.hs:     0/4   0%
haddock coverage for dist/build/tmp-28531/src/Utils/File.hs:     0/3   0%
haddock coverage for dist/build/tmp-28531/src/Frequency.hs:     0/6   0%
haddock coverage for dist/build/tmp-28531/src/Strategy.hs:     1/7  14%
haddock coverage for dist/build/tmp-28531/src/Content/Content.hs:     0/2   0%
haddock coverage for dist/build/tmp-28531/src/Utils/Multiline.hs:     1/2  50%

During interactive linking, GHCi couldn't find the following symbol:
  Allurezm0zi4zi2_UtilsziMultiline_multiline_closure
This may be due to you not asking GHCi to load extra object files,
archives or DLLs needed by your current session.  Restart GHCi, specifying
the missing library using the -L/path/to/object/dir and -lmissinglibname
flags, or simply by naming the relevant files on the GHCi command line.
Alternatively, this link failure might indicate a bug in GHCi.
If you suspect the latter, please send a bug report to:
  glasgow-haskell-bugs@haskell.org
}}}

The same problem for a library, with or without executables, with the same code. Hiding, in the library, the offending module Multiline does not help. The only thing that helps is eta-expanding the Multiline code as follows:

{{{
-multiline  = TQ.QuasiQuoter (TH.litE . TH.stringL) undefined undefined undefined
+multiline  = TQ.QuasiQuoter (\x -> (TH.litE . TH.stringL) x) undefined undefined undefined
}}}

and _not_ using the function in the only place where it's used.
",MikolajKonarski
4,188,Haddock reorders multiple declarations on one line,None,defect,2011-11-13T13:30:59Z+0000,2012-09-25T12:09:55Z+0100,"I have a source file containing the line:

i,j,k :: Num k => Quaternion k

The relevant line of the Haddock documentation comes out as:

i, k, j :: Num k => Quaternion k

(Note the reordering.)

Although not strictly incorrect, this distorts the semantic intent of the documentation.

The reordering also happens in other cases, eg:
http://hackage.haskell.org/packages/archive/HaskellForMaths/0.4.1/doc/html/Math-Algebras-Quaternions.html
http://hackage.haskell.org/packages/archive/HaskellForMaths/0.4.1/doc/html/Math-Algebras-Octonions.html
",DavidAmos
4,189,Incorrect or at least misleading output with PolyKinds + TypeOperators,None,defect,2011-11-25T18:22:53Z+0000,2012-09-25T12:09:55Z+0100,"The code

{{{
{-# LANGUAGE PolyKinds, ConstraintKinds, TypeOperators, MultiParamTypeClasses, FlexibleInstances, UndecidableInstances #-}
class    (c a, d a) => (c :&: d) a
instance (c a, d a) => (c :&: d) a
}}}

produces the following documentation for the instance:

{{{
Instances
(c a, d a) => (k :&: c) d a
}}}

I don't know where it should be, but that k is clearly not in the right place.",illissius
4,190,Extend the syntax of URL hyperlinks so that they can have link texts,None,enhancement,2011-12-16T04:23:02Z+0000,2012-09-25T12:09:55Z+0100,"There is currently no way to create URL hyperlinks having link texts, that is:
{{{
--| <http://example.net/>
}}}
renders to http://example.net/, but we can't create links that look like [http://example.net/ EXAMPLE]. I need something like:
{{{
--| <http://example.net/ EXAMPLE>
}}}",PHO
4,191,Incorrect handling of character references,None,defect,2012-01-09T03:47:07Z+0000,2012-09-25T12:09:55Z+0100,"In Haddock, a character reference such as &#252; is used to represent non-ASCII characters, such as the German umlaut ""u.

However, this does not work in the following situations:

* if the character appears in italics, 
* if the character appears in a code block with "">"",
* if the character appears in a URL.

Moreover, if such a character appears in a Haskell identifier between single quotes, the character is rendered correctly, but the word is not recognized as a Haskell identifier (and therefore the surrounding quotes are copied to the output and the identifier not linked).

See the attached file for examples. 

Here are some comments on how I think it could be fixed. In my opinion, the best way to handle the &#252; syntax would be to treat it as an input encoding, i.e., handle it at the I/O level, before any lexing and parsing is done by Haddock proper. In other words, the sequence &#252; should be treated as if it were a single character literally present in the input file. 

If it were done this way, then one could use the &#252; in *every* context, and one could even use escapes to represent actual ASCII characters, for example, &#38; to represent a literal ""&"". Thus, if the sequence of 6 characters &#252; had to appear literally in a comment, one could type it as &#38;#252; - although &\#252; would achieve the same result in a simpler way.
",selinger
3,193,Links to sections,None,enhancement,2012-02-05T09:55:21Z+0000,2012-09-25T12:09:55Z+0100,"It would be nice if we could link to certain sections withing a document.

Example:
{{{
module Foo (
-- * Foo
..
..
-- * Bar
-- | Read more in [Foo]
..
..
) where

}}}

As a precondition, we would need a way to address section in a unique manner.

This is somewhat related to #190 (both, #190 and this, require syntax extensions for new kinds of links).",SimonHengel
3,194,Stricter than GHC about newtypes in FFI code,None,defect,2012-02-13T21:33:08Z+0000,2012-09-25T12:09:55Z+0100,"Hi,

this is Haddock version 2.10.0 as shipped with GHC 7.4.1. The package GLUT-2.1.2.1 contains FFI code that GHC warns about, but haddock fails:

{{{
[ 9 of 21] Compiling Graphics.UI.GLUT.Window ( Graphics/UI/GLUT/Window.hs, dist-ghc/build/Graphics/UI/GLUT/Window.o )

Graphics/UI/GLUT/Window.hs:113:1:
    Warning: newtype `Window' is used in an FFI declaration,
             but its constructor is not in scope.
             This will become an error in GHC 7.6.1.
    When checking declaration:
      foreign import ccall unsafe ""static glutCreateWindow"" glutCreateWindow
        :: CString -> IO Window
}}}
vs.
{{{
Running Haddock for GLUT-2.1.2.1...
Running hscolour for GLUT-2.1.2.1...
Preprocessing library GLUT-2.1.2.1...
Warning: The documentation for the following packages are not installed. No
links will be generated to these packages: rts-1.0
Preprocessing library GLUT-2.1.2.1...
[..]
Graphics/UI/GLUT/Window.hs:113:1:
    Unacceptable result type in foreign declaration: IO Window
    When checking declaration:
      foreign import ccall unsafe ""static glutCreateWindow"" glutCreateWindow
        :: CString -> IO Window
}}}

But something is fishy, the {{{[..]}}} part contains a few of the {{{Warning: newtype `CInt' is used in an FFI declaration,}}} warnings, so maybe something else is amiss here.",nomeata
3,195,Duplicate documentation on records,None,defect,2012-03-09T21:45:48Z+0000,2012-09-25T12:09:55Z+0100,"Haddock has strange behavior for occurrences when you document the same field on different constructors of a record type: it includes all of the documentation every time it displays that field.

Here's one quick example that can reproduce the issue:


{{{
cabal update && cabal unpack QuickCheck-2.4.2 && cd QuickCheck-2.4.2 && cabal configure && cabal haddock && firefox ./dist/doc/html/QuickCheck/Test-QuickCheck.html#t:Result
}}}
",DanBurton
3,198,haddock-2.10.0 (shipped with ghc-7.4.1) crash,None,defect,2012-03-28T12:44:27Z+0100,2012-09-25T12:09:55Z+0100,"{{{
haddock: internal error: utils/haddock/src/Haddock/Backends/Xhtml/Layout.hs:204:9-37: Irrefutable pattern failed for pattern Haddock.Types.Documented n
                                                                                     mdl
}}}

in our large http://trac.informatik.uni-bremen.de:8080/hets project
(after deleting docs/index.html and ""make doc"") 
",maeder
5,199,put space between modul and (short) description,None,task,2012-03-28T12:52:12Z+0100,2012-10-14T01:15:49Z+0100,"http://www.informatik.uni-bremen.de/agbkb/forschung/formal_methods/CoFI/hets/src-distribution/versions/Hets/docs/
The text following the ""Description :"" tag in the haddock header is not separated from the modul link.",maeder
4,200,Latex backend issues,,defect,2012-04-01T17:57:38Z+0100,2012-04-01T17:57:38Z+0100,"Henning Thielemann reports:

>I could not compile generated LaTeX documents due to some
> underscores in module names like Paths_foobar (LaTeX sometimes an extra
> backslash in front of an underscore). I was also concerned with the two
> files 'main.tex' for the main document file and 'Main.tex' for the Main
> module. In a case-insensitive file system like the one of Windows this would
> lead to a conflict.

",waern
4,201,"Strip one leading blank from each line of a code block, if possible",None,enhancement,2012-04-12T08:11:32Z+0100,2012-09-25T12:09:55Z+0100,"Most people (including me) tend put a leading blank on each non-empty line of a code block.

Say

{{{
-- > foobar
}}}

instead of

{{{
-- >foobar
}}}

(e.g. test-framework-th contains [http://hackage.haskell.org/packages/archive/test-framework-th/0.2.2/doc/html/src/Test-Framework-TH.html#defaultMainGenerator real world examples])

The generated HTML documentation retains these leading blanks.  And if you copy&paste some example snippets from the documentation, you end up striping these leading blanks manually.

This has annoyed me several times. So I suggest to strip (in the parser) exactly one leading blank from each non-empty line of a code block iff each non-empty line of that code block starts with a blank.

In addition I'd adjust the default CSS to make up for the missing blank.",SimonHengel
4,203,very difficult to list pragmas in haddock code blocks,None,defect,2012-04-28T00:45:42Z+0100,2012-09-25T12:09:55Z+0100,"I would like to embed this as a code block in haddock:

{{{
> {-# LANGUAGE QuasiQuotes #-}
> import Data.Char        (toUpper)
> import HSX.QQ           (hsx)
> import HSX.XMLGenerator
>
> html :: (XMLGenerator m) => XMLGenT m (XMLType m)
> html = [hsx| <p><% map toUpper ""hello, world!""  %></p> |]
}}}

But, the LANGUAGE pragma gets stripped out. I can do this inside the normal part of the haddock comment:

    {&#45;\# LANGUAGE QuasiQuotes \#&#45;}

And it renders as desired. However, if I put that inside the code block, it does not get stripped out, but it also does not get unescaped. So, it shows up exactly like that.

As far as I can tell, there is no way to actually show the pragma in the code block.",JeremyShaw
3,206,Add markup support for properties,None,enhancement,2012-06-13T11:01:05Z+0100,2012-09-25T12:09:55Z+0100,"Some libraries, e.g. [http://hackage.haskell.org/packages/archive/filepath/1.3.0.0/doc/html/System-FilePath-Posix.html filepath] include properties in documentation.  It would be useful to have dedicated markup for properties, so that Doctest can extract an test properties with QuickCheck.",SimonHengel
3,207,haddock: internal error: spliceURL UnhelpfulSpan,None,defect,2012-06-18T18:29:03Z+0100,2012-09-25T12:09:55Z+0100,"With Haddock 2.8, I got this error message occasionally; with Haddock 2.9.4, I get it *all the time*. Minimal example attached.

The problem seems to arise when one has some function without a type signature, and the --source-entity option is used. The old behavior (2.8) was to ignore such a function. The new behavior is to generate the type signature, but then fail with the above error message.

To reproduce: 

haddock -h HaddockBug.hs --source-entity=HaddockBug.html#line-%L

Obviously, the above error message was not intended for end users; ""Missing type signature"" or ""Can't find this line in your file"" would be a better error message. Still better would be not to produce an error at all.
",selinger
3,208,Pattern match failure when processing code using kind variables,None,defect,2012-06-22T17:47:26Z+0100,2012-09-25T12:09:55Z+0100,"When haddock processes the following line

{{{
data family Sing (a :: k)
}}}

it issues the following error:

{{{
haddock: internal error: Pattern match failure in do expression at src/Haddock/Interface/Create.hs:65:3-10
}}}

This may be related to #202, but I believe I have the most updated version of haddock (HEAD from darcs.haskell.org/haddock.git) and I still get the error.",goldfire
3,209,"Failure in ""renameType"" when dealing with Template Haskell and tuples",None,defect,2012-07-22T01:57:07Z+0100,2012-09-25T12:09:55Z+0100,"I cannot yet use Haddock to document the ''singletons'' library (available on HackageDB / cabal-install). The problem line is line 64 of Singletons/Lib.hs, which uses Template Haskell to generate declarations for promoted tuple types and kinds. (haddock runs without error with that line removed.) I have tried to create a small test case, but I have been unable to do so.

This was tested on a build in the GHC tree with GHC version 7.5.20120720. The reported haddock version is 2.11.0.
",goldfire
3,210,"""failed to parse haddock prologue from file"" error when using non-ASCII characters in .cabal synopsis",None,defect,2012-08-13T18:38:58Z+0100,2012-10-14T14:57:39Z+0100,"However, haddock stops failing if an ASCII(or prepended with > or ""о"") description is supplied in cabal package.[[BR]]
Minimal example is attached.

haddock-2.10.0, ghc-7.4.1",exbb2
3,211,() is not hyperlinked anymore,2.13.2,defect,2012-09-21T11:34:09Z+0100,2012-10-15T13:37:18Z+0100,"I adapted the tests for now:

https://github.com/ghc/haddock/commit/85665a576b76cdc856ad3727b28a8abe5d185d59

I have no idea which commit introduced that regression.  Finding the commit in a systematic way would require code bisection in GHC's source tree (due to changes to Haddocks interface file and the GHC API).  However, I'm not aware of a systematic way to do code bisection in GHC's source tree.",SimonHengel
3,212,Investigate unexpected change with (Monad (Either e)),2.13.2,task,2012-09-21T15:09:30Z+0100,2012-12-10T13:41:42Z+0000,see: https://github.com/ghc/haddock/commit/47e6c8e77a4b8edbb1e4869ba5a0f76ee71ad8bb,SimonHengel
5,214,html themes are searched even if no html output has been requested,None,defect,2012-09-29T08:23:28Z+0100,2012-10-14T14:57:43Z+0100,"The offending line is

src/Main.hs, line 230
themes   <- getThemes libDir flags >>= either bye return

If <libdir>/html does not exists, getDirectoryContents (as called in getDirectoryItems, src/Haddock/Backends/XHtml/Themes.hs) fails with an IOError that is not caught.

Fix: move the line into each case for html output (e.g. after lines 232, 238, 245)

This bug is present in the ghc 7.6, and 7.4.2 branches, hence I attribute it to the 2.12 version.

Severity is rather low. Few users will experience that I assume. One scenario is that you install a package locally without documentation and then generate e.g. latex docu.
",lars_e_krueger
4,215,vimhelp backend updated for ghc-7.4.2,None,enhancement,2012-09-29T08:27:44Z+0100,2012-10-14T14:57:43Z+0100,"I included 2 patches in the attachment.

submission_20120929_ghc-7.4.1.patch applies to tag ghc_7.4.1-release
submission_20120929_ghc-7.4.2.patch applies to tag ghc_7.4.2-release

For some reasons I have haddock 2.10.0 together with ghc 7.4.2 on my system (Gentoo with haskell overlay). Hence, I prepared both patches",lars_e_krueger
4,217,Remove import of Haddock.Types from the backends,None,defect,2012-10-10T03:33:57Z+0100,2012-10-14T14:57:43Z+0100,Replace it with a new exported module (say Documentation.Haddock.Types) so that external backends are not broken when types are added.,hamish
3,218,Firefox dislikes Haddock master index on Windows,,defect,2012-10-10T14:51:18Z+0100,2012-10-10T17:46:38Z+0100,"(NB: This bug was ported here from the haskell platform trac: http://trac.haskell.org/haskell-platform/ticket/148 -- it might very well be fixed already!)

If you edit the cabal configuration file and add the lines

  documentation: True
  doc-index-file: $datadir\doc\index.html
then cabal-install generates a master package index every time it installs a new package. Internet Explorer is perfectly happy with this page, and the W3C validator passes it, but Firefox dislikes it.

Specifically, Firefox won't follow any of the links, complaining that ""the transfer protocol is not registered"". Basically, all of the links are absolute paths that begin ""C:\Documents and Settings\..."", and Firefox apparently thinks that ""C:"" is a transfer protocol specification, just like ""http:"" or ""mailto:"". (I'm using Firefox 3.5 for Windows, in case it makes a difference.)

Note that this bug does not affect the index of packages supplied with HP, which uses relative paths. This index page works with every browser I've tried. It's the absolute paths in the cabal-install package index that are failing.

Since the document index is always in the folder above the individual package documentation, I would suggest that making Haddock always use relative paths would fix this. (The alternative is to prefix all absolute paths with ""file:"", which seems to make Firefox happy.)
",MtnViewMark
4,219,No links from packages back to Haddock index,None,enhancement,2012-10-10T17:11:49Z+0100,2012-10-14T14:57:43Z+0100,"(NB: this ticket imported from a haskell platform ticket: http://trac.haskell.org/haskell-platform/ticket/151 )

With the right settings, Haddock generates a master package index that shows the modules for all installed packages and lets you navigate to them. Once you do so, however, there is no way to navigate back to the package index again. It would be nice if we could fix this.

HP 2010.2.0.0 (and previous version).

(Not sure if the version of haddock is correct in this ticket)",MtnViewMark
3,221,references to identifiers are not recognized in emphasized text,2.13.2,defect,2012-10-14T20:11:24Z+0100,2012-10-14T20:11:33Z+0100,"Minimal example:

{{{
-- | /some `foo` text/
foo :: Int
foo = 23
}}}",SimonHengel
3,222,Accept any input when parsing documentation,2.13.2,defect,2012-10-15T00:46:33Z+0100,2012-10-15T00:46:33Z+0100,"The parser for documentation should never fail.  If something is no valid Haddock syntax, then it can still be parsed as ordinary text.

E.g. the following is currently a parse error:

{{{
foo bar
> baz
}}}

But we should instead parse it as:

{{{
DocParagraph (DocString ""foo bar\n> baz\n"")
}}}

That's the way most Markdown parsers do it.",SimonHengel
3,223,Deprecation messages for re-eported items from other packages get lost,2.13.2,defect,2012-10-15T09:25:35Z+0100,2012-10-15T09:25:35Z+0100,,SimonHengel
3,224,"Link to ""Source"" is not separate by whitespace from preceding content",,defect,2012-10-21T19:47:50Z+0100,2012-10-21T21:08:22Z+0100,"This is annoying when you try to visually mark/select a word, e.g. if you try to select [http://hackage.haskell.org/packages/archive/base/4.6.0.0/doc/html/System-IO.html#g:22 openTempFile] in Firefox (with double a click) the ""Source"" link will get selected, too.",SimonHengel
3,225,no documentation for re-exported renamed modules,,defect,2012-11-01T18:09:27Z+0000,2012-11-01T18:13:25Z+0000,"With a deep module heirarchy and modules re-exporting many modules, I find this syntax much less verbose:

{{{
module Foo (module M) where
import Bar as M
import Baz as M
}}}

But haddock makes no useful documentation.

The verbose repetitive syntax works as expected with links to the re-exported modules:

{{{
module Foo
  ( module Bar
  , module Baz
  ) where
import Bar
import Baz
}}}

It would be very nice if haddock recognised module renaming and generated appropriate links to the re-exported modules - as it is now I'm going to have to go back to listing everything twice so that documentation is useable.
",claude
3,226,Add a mechanism to prune deprecated things,,defect,2012-11-04T17:18:10Z+0000,2012-11-04T17:18:10Z+0000,"Sometimes you want to keep a deprecated function around, but you do not want it to clutter the documentation.

A more general approach would be to allow an optional list of arguments to prune, so that functions can be omitted selectively.",SimonHengel
4,227,Do not require an empty line between list items,,enhancement,2012-11-04T19:33:29Z+0000,2012-11-04T19:33:41Z+0000,"Currently the following is not accepted as a list:
{{{
* foo
* bar
}}}

You have to write the following instead:

{{{
* foo

* bar
}}}

I think both forms should be permitted (if only for compatibility with other systems).",SimonHengel
3,228,Wrong links for fully qualified identifiers that are not in scope,2.13.2,defect,2012-11-15T15:35:21Z+0000,2013-02-04T22:49:07Z+0000,"If we have something like

{{{
'Control.Concurrent.MVar.addMVarFinalizer'
}}}

Haddocks thinks it is a type and will prepend a {{t:}} to the generated link.

A real world example: http://hackage.haskell.org/packages/archive/base/4.6.0.0/doc/html/System-Mem-Weak.html#v:addFinalizer",SimonHengel
3,231,haddock --compatible-interface-versions,,defect,2012-12-12T12:12:49Z+0000,2012-12-12T12:12:49Z+0000,"It would be useful to be able to ask haddock what interface version it supports, e.g.
{{{
$ haddock --compatible-interface-versions
21 22
}}}

This would be similar to the existing {{{haddock --interface-version}}}.

If you wait long enough I might submit a patch ;-)",nomeata
3,232,Module re-exports are handled incorrectly,,defect,2012-12-12T13:29:31Z+0000,2012-12-12T17:03:07Z+0000,"Contrary to its documentation, Haddock.Interface.Create.moduleExports incorrectly assumes that for a module re-export all of its symbols are re-exported.

As an illustration, http://hackage.haskell.org/packages/archive/test-framework/0.8/doc/html/Test-Framework.html shows constructors of the Test data type, although it is exported as an abstract type.",feuerbach
3,233,"Haddock crashes ""internal error: renameType""",,defect,2013-01-01T01:03:59Z+0000,2013-01-01T01:03:59Z+0000,"When generating docs for https://github.com/mikeplus64/record/blob/master/src/Data/Record.hs, haddock crashes:

{{{
~/code/projects/record/src/Data> haddock Record.hs -v 3
Creating interfaces...
Haddock coverage:
Checking module Data.Record...
Creating interface...
doc comment parse failed:  See 'alter'
 > [alt|x|] == alter (undefined :: Key x)
doc comment parse failed:  See 'access'.
 > [get|x|] == access (undefined :: Key x)
Warning: Data.Record: Instances of type and data families are not yet supported. Instances of the following families will be filte
red out:
  Wrap, ++
Warning: Couldn't find .haddock for export GHC.TypeLits.Symbol
  43% ( 15 / 35) in 'Data.Record'
Attaching instances...
Building cross-linking environment...
Renaming interfaces...
haddock: internal error: renameType

~/code/projects/record/src/Data> haddock --version
Haddock version 2.12.0, (c) Simon Marlow 2006
Ported to use the GHC API by David Waern 2006-2008
}}}

This is installed from Arch Linux's [haskell] repository, which says the version is 2.13.1-2. cabal info haddock also says I have 2.13.1 installed. But I trust haddock --version more so that's the version I used for the ticket. :)",mikeplus64
3,234,Including documentation in the export list breaks headings,,defect,2013-01-04T15:46:44Z+0000,2013-01-04T15:48:56Z+0000,"Hi

Section [http://www.haskell.org/haddock/doc/html/ch03s04.html 3.4] describes how to add headings and sub-headings to the export list.
Section [http://www.haskell.org/haddock/doc/html/ch03s05.html 3.5] explains how to include documentation directly to the export list.

When mixing these features, the sub-heading following the included documentation is not considered.
 * Input: !FooBroken.hs
 * Output: !FooBroken.html (note the 5th row in particular)

Without the included documentation everything renders fine.
 * Input: !FooWorks.hs
 * Output: !FooWorks.html

I tried various alternatives such as adding and removeing additional empty lines between the heading and the included documentation. It seems to me that included documentation is simply not expected in between of a heading and its sub-heading.

Greetings,

Alex
",copton
4,237,Link to non-imported lowercase name generates a type link instead of a data link,,defect,2013-01-28T02:16:52Z+0000,2013-01-28T02:16:52Z+0000,"If you say e.g. `'Control.Concurrent.killThread'`, it generates a type link (t:killThread) instead of a data link (v:killThread).  Haddock 2.11.0 does not have this problem, but Haddock 2.12.0 does.

For example, the documentation for `ThreadKilled` refers to `killThread`:

 * [http://hackage.haskell.org/packages/archive/base/4.5.1.0/doc/html/Control-Exception.html#t:AsyncException Haddock 2.11.0 (base 4.5.1.0)] generates a :v link (correct)

 * [http://hackage.haskell.org/packages/archive/base/4.6.0.0/doc/html/Control-Exception.html#t:AsyncException Haddock 2.12.0 (base 4.6.0.0)] generates a :t link (incorrect)",joeyadams
3,239,Named chunk before imports causes error also if it is placed before module declaration.,,defect,2013-02-06T21:12:07Z+0000,2013-02-06T21:12:07Z+0000,"Haddock fails to parse file with:

Haddock coverage:

Test.hs:12:1: parse error on input `import'

When a named chunk is placed before imports. It works just fine after imports.

Similarly if the named chunk is placed before the module declaration causes haddock to fail with the same error.",Davorak
3,241,Ugly definition lists,,defect,2013-03-02T22:03:51Z+0000,2013-03-02T22:03:51Z+0000,"The HTML produced by definition lists in the comments of class methods is currently displayed rather uglily when styled by ocean.css. For example, the HTML page produced by haddock for following code is displayed (in Firefox, but in other browsers too) as follows:

{{{
module Blah (Blah (..)) where
 
-- | The 'Blah' type class.
class Blah a where
    -- | The 'foo' method. Here is a definition list:
    --
    --     [foo] This is the foo entry of the definition list.
    --
    --     [bar] This is the bar entry of the definition list.
    foo :: a -> a
    
    -- | The 'bar' method.
    bar :: a -> a

}}}

In Firefox:

[[Image(http://i.imgur.com/NMyfTOY.png)]]

As you can see, it's quite confused and unreadable. The problem is to do with floats not being cleared properly.

I've made a small change to ocean.css (and am attaching a patch with this change below) that significantly improves how the documentation for the above is displayed. This what it looks like now:

[[Image(http://i.imgur.com/LjTmNXF.png)]]",duairc
3,242,internal error: synifyKind,,defect,2013-03-14T08:11:03Z+0000,2013-03-14T08:11:03Z+0000,"{{{
module M (Proxy) where

import Data.Proxy -- from the 'tagged' package
}}}

yields

haddock: internal error: synifyKind
(haddock version 2.13.2)",feuerbach
3,243,Add markup parsing to the Haddock API,,enhancement,2013-03-25T08:31:02Z+0000,2013-03-25T08:31:02Z+0000,"The haddock library currently does not expose functionality for
converting strings of Haddock markup to HTML.

This functionality is needed by Hackage, for example, to render
package description text. Hackage duplicates the haddock parsing and
lexing code rather than using it directly:

http://code.haskell.org/hackage-server/Distribution/Server/Pages/Package/

We should add functions to the Haddock API for parsing the markup.",waern
3,244,Add Markdown support,,enhancement,2013-03-29T00:10:44Z+0000,2013-04-04T18:08:53Z+0100,"Markdown has become the standard markup for writing programming documentation (and blog posts and so on). It would be nice if Haddock could support a superset of Markdown (i.e. with support for identifier references and so forth) via a pragma:

{{{
{-# HADDOCK Markdown #-}
}}}

That way we could produce much richer docs, containing tables, bold text, section headers (without having to add those headers to the export list), etc.",tibbe
4,245,Module copyright and license info not included in XHTML output,,enhancement,2013-05-20T11:20:54Z+0100,2013-05-20T13:24:10Z+0100,"Haddock makes it possible to include some metadata in module headers. However, only some of this metadata is actually produced in the documentation.

Attached is a patch to include all relevant module metadata items in the generated module documentation.

I have not updated the golden tests to match, because the reference output files seem to be out-of-date even before this patch.

Also, this patch modifies the Binary instance for 'HaddockModInfo'. Does this mean I should increment the 'binaryInterfaceVersion' in 'Haddock.InterfaceFile'?",mboes
3,246,Haddock doesn't build with --enable-tests,,defect,2013-05-21T02:02:50Z+0100,2013-05-21T02:02:50Z+0100,"Haddock seems to build fine with simple ‘cabal configure && cabal build’. To let us run tests however, ‘cabal configure --enable-tests’ is needed first. With this flag however, a type error occurs (triple gotten where pair expected, see attachment). Also attaching a trivial workaround which seems to do the job.

>The Glorious Glasgow Haskell Compilation System, version 7.7.20130519
>Linux misaki 3.9.0-gentoo #1 SMP Thu May 9 20:39:14 BST 2013 i686 Intel(R) Core(TM)2 Duo CPU L7700 @ 1.80GHz GenuineIntel GNU/Linux

Tried with current HEAD (d15913bfcf44791a6c7668482dbc85d0e9102bb5).

",Fūzetsu