Haddock does not document exported fields of partially-exported records.

[BartMassey]

In System.Console.ParseArgs, I had in my module exports the line

    Args(argsUsage, argsProgName, argsRest),

which hides the export of the record constructor args. Unfortunately, Haddock fails to document the other exported constructors of the record (even their existence), making them essentially invisible to users. This is bad, because these constructors are necessary for many ParseArgs use cases.

I could probably work around this with some bletcherous module import chicanery, but I don't think it would be a good idea. Instead, I've got something gross in there for now that just renames args to __args and exports the whole record. I suppose I could play games with a typeclass, but bleah.

This issue was first reported seven years ago in http://trac.haskell.org/haddock/ticket/3, and was last updated 20 months ago. I don't understand Haddock well enough to offer a patch.

[harpocrates]

There are a couple of interesting issues here. Consider the following data declaration:

data P = P { a :: Int    -- ^ an int
           , b :: String -- ^ a string
           , c :: ()     -- ^ a unit
           }

The following are possible (but don't happen very often, AFAICT):

1. Export some record fields, the type, but not the constructor (module Main(P(a))). The record field is still a bit more than just a function, since it can be used to update an existing value (for x :: P, x { a = 3 } is valid as well as a x).

   Currently, Haddock doesn't mention a at all. In this case, Haddock could dump out record fields in a separate section (similar to "Bundled patterns") when the constructor is not exported. Something like

   data P
   
       _Orphan record fields_
   
        an int
          a :: Int
   

• Export some (but not all) record accessors, the type, and the constructor (module Main(P(a,P))). As before, a can be used as more than just a function.

  Currently, Haddock displays P as a non-record data constructor (and a is once again not mentioned). In this case, Haddock could display the record fields as records, and the non-exported record fields as non-records. Something like

  data P
  
      _Constructors_
     
       P
         a :: Int      an int
         String        a string
         ()            a unit
  

There are still a bunch of problems though: orphan GADT record fields need more than just their type (they need the output type of their constructor), what should the LaTeX backend do, etc.

[TravisCardwell]

I ran into this issue recently and found an easy workaround for my use case: export the accessor functions separately.

Example

In the following, constructor Foo is not exported so that users of the API must use foo to create a value of type Foo. This can be used to enforce an invariant that all Foo values are valid. Unfortunately, accessor functions bar and baz are not documented by Haddock.

module Foo
  ( Foo(bar, baz)
  , foo
  ) where

-- | Contrived example data type
data Foo
  = Foo
    { bar :: !Int  -- ^ some value @bar@
    , baz :: !Int  -- ^ some value @baz@
    }

-- | Construct a 'Foo' with validation
foo :: Int -> Int -> Either String Foo
foo = undefined

An easy workaround is to export accessor functions bar and baz separately. Since Haddock displays them as functions, the documentation for them should be written accordingly.

module Foo
  ( Foo
  , foo
  , bar
  , baz
  ) where

-- | Contrived example data type
data Foo
  = Foo
    { bar :: !Int  -- ^ Get some value @bar@
    , baz :: !Int  -- ^ Get some value @baz@
    }

-- | Construct a 'Foo' with validation
foo :: Int -> Int -> Either String Foo
foo = undefined