[Haskell-beginners] documenting individual method arguments with Haddock

Patrick Pelletier 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 
is desired
                                    -- 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?

Thanks,

--Patrick



More information about the Beginners mailing list