Allow grouping of functions with a corresponding data type

[ghc-mirror]

Original reporter: duncan

Suppose you're refactoring to use smart constructors. So you switch from exporting:

data WindowBits
 = WindowBits Int
 | DefaultWindowBits

to:

data WindowBits

defaultWindowBits :: WindowBits

windowBits :: Int -> WindowBits

Currently the former is presented with a more logical grouping than the latter. In the constructor case we get the docs for the whole lot all in one block which clearly indicates that they are related. With the latter, each smart constructor is just an independent top level function and only the order makes them look in any way related (obviously the names and types make them look related, but the structure and presentation does not).

So what I'd like is a way to group related top level exports, so that when there is a very strong relation, such as in the smart constructor case, I can indicate that in the markup and have it presented nicer.

Currently there is a disincentive to switch from constructors to smart constructors because it makes the API look bigger and less organised. This is a bit of a shame.

The obvious question is how should the grouping be indicated and how should it affect the default presentation.

[ghc-mirror]

Original reporter: duncan

This particularly affects the synopsis. Currently we get:

data WindowBits

defaultWindowBits :: WindowBits

windowBits :: Int -> WindowBits

each in their own grey div box. Ideally I want to present it as:

data WindowBits
 defaultWindowBits  :: WindowBits
 windowBits         :: Int -> WindowBits

in a single grey div.

In the detail section I want it to be something like:

data WindowBits

This specifies the size of the compression window. Larger
values of this parameter result in better compression at
the expense of higher memory usage.

The compression window size is the value of the the window
bits raised to the power 2. The window bits must be in the
range 8..15 which corresponds to compression window sizes
of 256b to 32Kb. The default is 15 which is also the
maximum size.

The total amount of memory used depends on the window bits
and the MemoryLevel. See the MemoryLevel for the details.

Constructor Functions
  defaultWindowBits :: WindowBits
  The default WindowBits is 15 which is also the maximum size.

  windowBits :: Int -> WindowBits
  A specific compression window size, specified in bits in
  the range 8..15

The appropriate place to indicate the grouping is almost certainly in the export list, eg:

  WindowBits,
  -- * Constructor Functions
    defaultWindowBits,
    windowBits,

or some similar suitable syntax to give a name to these related things. Perhaps it should not be a free form title, just like the existing "Constructors" is standard not free form. One of a small number of standard labels may be better.