Haddock on record fields Haskell

Question

I am trying write haddock for record fields on an interface. Only some of the fields are exported so I only want some of them documented. I read the documentation page here: http://www.haskell.org/haddock/doc/html/ch03s02.html#id565178

However, I cannot seem to get this to work. Here is the section I am trying to write haddock for:

{-|
Describes a Clients connection and provides an interface for
storing data associated with the client. Each client will be given
a unique cid and are Eq if their cid's are Eq.

A ClientConn comes packaged with two functions for storing additional
information in Strings, lookup and modify. The lookup function
takes a key and returns the current value of the key or the empty
string if it has never been set. The modify function
takes a key and value and updates it such that the next call to
lookup with that key will return the value provided.
-}
data ClientConn = ClientConn { -- | The Unique ID for this client
                               cid       :: Integer,
                               -- | A lookup function for this client
                               lookup    :: (String -> IO String),
                               -- | A modify function for this client
                               modify    :: (String -> String -> IO ()),
                               chandle   :: Handle,
                               host      :: Net.HostName,
                               pid       :: Net.PortNumber,
                               msgList  :: List String,
                               dead      :: MVar Bool,
                               timestamp :: TimeStamp,
                               tid       :: MVar (ThreadId, ThreadId),
                               lock      :: MVar Lock.Lock}

The comment for the data type shows up correctly in the generated haddock. However, none of the records are generated. I would like it to generate for the cid, lookup, and modify records.

Thanks in advance!

The full source can be found here: https://github.com/jcollard/simple-server/blob/master/Network/SimpleServer.hs

I've run into various bugs with haddock'ing records before that were almost always worked around by adding newlines before the haddock comment. Does that work here? — Daniel Wagner, Feb 16 '13 at 19:56
I added a new line before each haddock comment with no change to the generated output. I've also tried it with {-| -}. — Joe, Feb 16 '13 at 20:03
You can see the full source here: https://github.com/jcollard/simple-server/blob/master/Network/SimpleServer.hs — Joe, Feb 16 '13 at 20:16

score 3 · Accepted Answer · answered Feb 16 '13 at 22:25

Unfortunately, haddock doesn't currently support showing the documentation for only a few of a record's fields as fields of that record. You can work around this either by exporting all fields:

module Foo (ClientConn(..)) where ...

or by exporting the fields, but not as fields:

module Foo (ClientConn, cid, lookup, modify) where ...

In the latter case, the documentation will not automatically indicate that these functions are actually fields, but they will be usable in record syntax.

Good to know. For now, I will export them separately and not as fields. — Joe, Feb 16 '13 at 22:33

Haddock on record fields Haskell

1 Answers1