Ticket #59 (closed defect: fixed)

Opened 6 years ago

Last modified 2 years ago

Template Haskell generated declarations problematic

Reported by: nomeata Owned by:
Priority: major Milestone:
Version: Keywords: TH



with haddock > 2.0, it is possible to generate documentation for sources with TH generated top level declartaions. This is very handy, especially as it is often not clear to the user of a library, what declarations a TH function generates, and what types they have.

With haddock-2.2.2, I observed that haddock includes some TH generated declarations. Aside the fact that TH-generated functions need to have TH-generated type signatures for haddock to notice them, just like manual functoins, it skipped some of them without apparent reason.

With some code reading, I found out that haddock throws aways all but one declaration per source location – but with Template Haskell, there can be more than one per source location! The following patch fixes it for me:

diff -rN -u old-haddock/src/Haddock/Interface/Create.hs new-haddock/src/Haddock/Interface/Create.hs
--- old-haddock/src/Haddock/Interface/Create.hs	2008-10-05 01:40:22.785419074 +0200
+++ new-haddock/src/Haddock/Interface/Create.hs	2008-10-05 01:40:22.813422082 +0200
@@ -327,9 +327,7 @@
     _ -> case d of
       Nothing -> collect (Just e) doc_so_far es
-      Just d0
-        | sameDecl d0 e -> collect d doc_so_far es  
-        | otherwise -> finishedDoc d0 doc_so_far (collect (Just e) DocEmpty es)
+      Just d0 -> finishedDoc d0 doc_so_far (collect (Just e) DocEmpty es)
 finishedDoc :: LHsDecl Name -> HsDoc Name -> [DeclWithDoc] -> [DeclWithDoc]
@@ -340,10 +338,6 @@
     notDocDecl _              = True
 finishedDoc _ _ rest = rest
-sameDecl d1 d2 = getLoc d1 == getLoc d2
 mkSubMap :: HsGroup Name -> Map Name [Name]
 mkSubMap group = Map.fromList [ (name, subs) | L _ tycld <- hs_tyclds group,
  let name:subs = map unLoc (tyClDeclNames tycld) ]

I’m not entirely sure what the side effects are. In what cases are more than one declarations per source location where one of them should be dropped? I don’t think that that happens often, because (if I read the code correctly), it is not specified which declaration should be dropped in such a case.

I have attached a darcs patch with this change. I’d greatly welcome better TH support in haddock.


Change History

Changed 6 years ago by nomeata

Changed 6 years ago by waern

Thanks for the patch and for pointing out this problem! You are right that Haddock can't handle multiple declarations with the same SrcLoc? properly. I'll look at your patch as soon as I have the time.

Changed 6 years ago by anonymous

  • milestone set to 2.4.2

Changed 6 years ago by waern

  • status changed from new to closed
  • resolution set to fixed

Patch applied, thanks!

Changed 6 years ago by SamB

  • keywords TH added

Changed 2 years ago by anonymous

  • milestone 2.4.2 deleted

Milestone 2.4.2 deleted

Note: See TracTickets for help on using tickets.