Send Beginners mailing list submissions to
beginners@haskell.org
To subscribe or unsubscribe via the World Wide Web, visit
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
or, via email, send a message with subject or body 'help' to
beginners-requ...@haskell.org
You can reach the person managing the list at
beginners-ow...@haskell.org
When replying, please edit your Subject line so it is more specific
than "Re: Contents of Beginners digest..."
Today's Topics:
1. documenting individual method arguments with Haddock
(Patrick Pelletier)
----------------------------------------------------------------------
Message: 1
Date: Fri, 27 May 2016 23:53:56 -0700
From: Patrick Pelletier <c...@funwithsoftware.org>
To: beginners@haskell.org
Subject: [Haskell-beginners] documenting individual method arguments
with Haddock
Message-ID: <57494084.7050...@funwithsoftware.org>
Content-Type: text/plain; charset=utf-8; format=flowed
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@.
-> 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
------------------------------
Subject: Digest Footer
_______________________________________________
Beginners mailing list
Beginners@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/beginners
------------------------------
End of Beginners Digest, Vol 95, Issue 32
*****************************************
