Problem with haddock - it dislikes my comments

Having just read the Haddock manual , I am haddocking (may I copyleft that verb?) my code. But half-way through this data type, I discover that haddock rejects my non-haddock comments, although GHC is fine: -- | Non-interactive representation of a Chu Shogi move data Move = Pass Piece Coordinate -- ^ Double move to empty square and back to origin | Igui Piece Coordinate -- ^Capture without moving Piece Coordinate -- Captured piece | Double_move Piece -- ^ Other double moves Coordinate -- Initial location Coordinate -- First destination (Maybe Piece) -- Capture? Coordinate -- Second destination (Maybe Piece) -- Capture? | Capture Piece Coordinate Piece Coordinate Bool -- Promote? Bool -- Declined to promote | Move Piece Coordinate Coordinate Bool Bool How can I document the components of each constructor? -- Colin Adams Preston Lancashire

On Sat, Feb 28, 2009 at 2:59 PM, Colin Paul Adams
Having just read the Haddock manual , I am haddocking (may I copyleft that verb?) my code.
But half-way through this data type, I discover that haddock rejects my non-haddock comments, although GHC is fine:
-- | Non-interactive representation of a Chu Shogi move data Move = Pass Piece Coordinate -- ^ Double move to empty square and back to origin | Igui Piece Coordinate -- ^Capture without moving Piece Coordinate -- Captured piece | Double_move Piece -- ^ Other double moves Coordinate -- Initial location Coordinate -- First destination (Maybe Piece) -- Capture? Coordinate -- Second destination (Maybe Piece) -- Capture? | Capture Piece Coordinate Piece Coordinate Bool -- Promote? Bool -- Declined to promote | Move Piece Coordinate Coordinate Bool Bool
How can I document the components of each constructor?
http://trac.haskell.org/haddock/ticket/60 ? -- gwern

"Gwern" == Gwern Branwen
writes:
Gwern> On Sat, Feb 28, 2009 at 2:59 PM, Colin Paul Adams
Gwern>

"Colin" == Colin Paul Adams
writes:
"Gwern" == Gwern Branwen
writes: Gwern> On Sat, Feb 28, 2009 at 2:59 PM, Colin Paul Adams Gwern> wrote: >>> Having just read the Haddock manual , I am haddocking (may I >>> copyleft that verb?) my code. >>> >>> But half-way through this data type, I discover that haddock >>> rejects my non-haddock comments, although GHC is fine:
>>> How can I document the components of each constructor? Gwern> http://trac.haskell.org/haddock/ticket/60 ? Colin> That seems to be a different bug - my haddock comments are Colin> accepted fine - it's the plain Haskell ones (no ^) that it Colin> complains about as a parse error. No, I'm wrong - it does seem to be the same problem. Since the ticket has been downgraded to a minor problem, it seems the Haddock team doesn't want to allow documentation of components, except when they are named fields. -- Colin Adams Preston Lancashire

"Colin" == Colin Paul Adams
writes:
"Colin" == Colin Paul Adams
writes: "Gwern" == Gwern Branwen writes: Gwern> On Sat, Feb 28, 2009 at 2:59 PM, Colin Paul Adams Gwern> wrote: >>>> Having just read the Haddock manual , I am haddocking (may I >>>> copyleft that verb?) my code. >>>> >>>> But half-way through this data type, I discover that haddock >>>> rejects my non-haddock comments, although GHC is fine:
>>>> How can I document the components of each constructor? Gwern> http://trac.haskell.org/haddock/ticket/60 ? Colin> That seems to be a different bug - my haddock comments are Colin> accepted fine - it's the plain Haskell ones (no ^) that it Colin> complains about as a parse error. Colin> No, I'm wrong - it does seem to be the same problem. Colin> Since the ticket has been downgraded to a minor problem, it Colin> seems the Haddock team doesn't want to allow documentation Colin> of components, except when they are named fields. The by-pass seems to avoid haddock comments - it means i have to read the source code to see my comments - well, I don't mind, but it seems to make Haddock pointless. -- Colin Adams Preston Lancashire

2009/2/28 Colin Paul Adams
"Colin" == Colin Paul Adams
writes: "Gwern" == Gwern Branwen
writes: Gwern> On Sat, Feb 28, 2009 at 2:59 PM, Colin Paul Adams Gwern> wrote: >>> Having just read the Haddock manual , I am haddocking (may I >>> copyleft that verb?) my code. >>> >>> But half-way through this data type, I discover that haddock >>> rejects my non-haddock comments, although GHC is fine: >>> How can I document the components of each constructor?
Gwern> http://trac.haskell.org/haddock/ticket/60 ?
Colin> That seems to be a different bug - my haddock comments are Colin> accepted fine - it's the plain Haskell ones (no ^) that it Colin> complains about as a parse error.
No, I'm wrong - it does seem to be the same problem.
In fact, it's not. I've added two new tickets for your problem: http://trac.haskell.org/haddock/ticket/95 http://trac.haskell.org/haddock/ticket/94
Since the ticket has been downgraded to a minor problem, it seems the Haddock team doesn't want to allow documentation of components, except when they are named fields.
Again, not the same problem. The ticket is about documenting empty data declarations on the same line, e.g: data Empty -- ^ A comment Since you can just put the comment above or below the declaration, I consider it a minor problem. We have more serious bugs to focus on :) The new tickets for your problem have been assigned major priority, though. Thanks, David
participants (3)
-
Colin Paul Adams
-
David Waern
-
Gwern Branwen