Ticket #289 (closed defect: invalid)

Opened 4 months ago

Last modified 4 months ago

Parse Error

Reported by: Kron Owned by:
Priority: minor Milestone:
Version: 2.13.2.1 Keywords:
Cc:

Description

I ran into a parse error, and the documentation told me to report parse errors.

I was trying to add markup to describe the individual elements of a tuple in a type synonym.

--   Region = (floorX, floorY, ceilX, ceilY)
type Region = (Int, -- ^ floorX
               Int,
               Int,
               Int)

... After which it collapsed with the following error:

kron@navi:~/Programming/Haskell/Libraries$ haddock -h -o QuadTree\ Haddock/ QuadTree.hs
Haddock coverage:

QuadTree.hs:227:21: parse error on input `-- ^ floorX'

Change History

Changed 4 months ago by Fūzetsu

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

The documentation should probably be a bit clearer. There are two types of parse errors (which unhelpfully have the same message).

1. A Haddock comment is in the wrong place, somewhere we don't know what it means.

2. A doc itself can't be parsed.

If it were 2. that you're reporting, then it'd be a bug. What you're reporting is 1. and is something we don't support. You can document the whole tuple like

type Region = (Int, Int, Int, Int) -- ^ doc for fields

The only thing that we allow the user to document each element are fields of records. There are multiple tickets requesting that this be extended to other stuff.

Perhaps we should clear this up in docs.

Note: See TracTickets for help on using tickets.