Illegal position of Haddock comment [GHC-94458]

Flag: -Winvalid-haddock

Haddock comments are used to document entities of Haskell programs, and are used to generate API documentation which can be displayed on Hackage or as tooltips in editors. This error is emitted when a Haddock comment is attached to an entity that cannot be documented this way. A normal comment should be used instead.

Examples

Illegal Haddock comments for definitions in where clause

In this example, the user tried to document the two identifiers fizz and buzz that are introduced in a local where clause. Since these identifiers are not part of the public API, a warning is emitted that Haddock comments are not allowed in that place. A normal comment can be used instead.

messages/GHC-94458/illegalHaddockComment/before/IllegalHaddockComment.hs:5:5: warning: [GHC-94458] [-Winvalid-haddock]
    A Haddock comment cannot appear in this position and will be ignored.
  |
5 |     -- | The sound of a refreshing beverage.
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

messages/GHC-94458/illegalHaddockComment/before/IllegalHaddockComment.hs:7:5: warning: [GHC-94458] [-Winvalid-haddock]
    A Haddock comment cannot appear in this position and will be ignored.
  |
7 |     -- | The sound of an annoying fly.
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

IllegalHaddockComment.hs

Before

module IllegalHaddockComment where

main = print (fizz ++ buzz)
  where
    -- | The sound of a refreshing beverage.
    fizz = "fizz"
    -- | The sound of an annoying fly.
    buzz = "buzz"

After

module IllegalHaddockComment where

main = print (fizz ++ buzz)
  where
    -- The sound of a refreshing beverage.
    fizz = "fizz"
    -- The sound of an annoying fly.
    buzz = "buzz"