[Haskell-beginners] documenting individual method arguments with Haddock
code at funwithsoftware.org
Sat May 28 06:53:56 UTC 2016
In Haddock, individual function arguments can be documented like this:
f :: Int -- ^ The 'Int' argument
-> Float -- ^ The 'Float' argument
-> IO () -- ^ The return value
Since a typeclass method is very much like a function, I assumed I could
document individual arguments of methods the same way. For example:
-- | Class representing a connection to a collection of bulbs.
-- In the case of a LAN connection, this would be all bulbs on the LAN.
-- In the case of a cloud connection, this would be all bulbs associated
-- with the cloud account for a particular access token.
class Connection t where
-- | Retrieve information about some or all lights. Corresponds to
-- <http://api.developer.lifx.com/docs/list-lights List Lights> endpoint.
-- Beware that on a @LanConnection@, it takes time for lights to be
-- discovered, so the list of lights will be empty immediately after
-- the connection is created.
listLights :: t -- ^ The connection.
-> [Selector] -- ^ The lights to list.
-> [InfoNeeded] -- ^ A hint about what information
-- in the results. This hint is used
-- by @LanConnection@, but is ignored by
-- @CloudConnection at .
-> IO [LightInfo]
However, when I generate documentation (using Haddock 2.17.2, via "stack
haddock"), the text "A hint about what information is desired" doesn't
appear anywhere in the generated documentation.
Is there a way I can include this sort of per-argument documentation for
my typeclass methods?
More information about the Beginners