[haddock] #3: feature request: record types with partially exported fields

[haddock]

#3: feature request: record types with partially exported fields
------------------------+---------------------------------------------------
Reporter:  avatariks    |        Owner:  somebody
    Type:  enhancement  |       Status:  new     
Priority:  major        |    Milestone:          
 Version:               |   Resolution:          
Keywords:               |  
------------------------+---------------------------------------------------
Changes (by duncan):

 * cc: duncan (added)
  * priority:  minor => major

Comment:

 Resetting priority. This makes the difference between the technique being
 usable or not. If none of the fields get documented then nobody can
 decipher the api.

 My example is the `tar` package. I have a tar `Entry` type which is a
 record with a number of fields. I want to export record selectors so that
 user can do things like:

 {{{
 (fileEntry name content) { fileMode = executableFileMode }
 }}}

 However I do not want clients to be able to construct an Entry directly.
 We provide `emptyEntry` with default fields to be overridden. This lets us
 add new fields and guarantee that no client will break because they cannot
 mis-use the constructor by doing something like:

 {{{
 Entry blah blah blah ...
 }}}
 ie use it directly and then break when I add a field.

 However if I do not export the constructor then the API docs do not
 mention any of the fields. It becomes just:

 {{{
 data Entry
   Tar archive entry
 }}}

 So, how would we document a record where the constructor(s) are not
 exported. Well, when the constructor is exported it looks like:

 {{{
 data Entry
   Tar archive entry
 Constructors
   Entry
     filePath :: !TarPath        Path of the file or directory.
     fileMode :: !FileMode       UNIX file mode (file permissions).
     ... etc
 }}}

 So how about exactly the same but omit the Constructor name:

 {{{
 data Entry
   Tar archive entry
 Constructors
     filePath :: !TarPath        Path of the file or directory.
     fileMode :: !FileMode       UNIX file mode (file permissions).
     ... etc
 }}}

 If there were multiple constructors then that's also ok, we can keep the
 blocks of record names together. Just omit the constructor name div.

 Similarly if we do not export all record fields names, just omit that one
 from the listing. Rather than switching to positional constructor style as
 it does now.

 For the synopsis it displays using Haskell syntax. Here it's harder to
 omit the constructor and have it look sane. Still we can probably just do
 it anyway. One of:

 {{{
 data Entry = {
   filePath :: !TarPath
   fileMode :: !FileMode
   ...
 }
 }}}

 {{{
 data Entry = _ {
   filePath :: !TarPath
   fileMode :: !FileMode
   ...
 }
 }}}

 or

 {{{
 data Entry {
   filePath :: !TarPath
   fileMode :: !FileMode
   ...
 }
 }}}

 Each generalises to multiple missing or exported alternative constructors:

 {{{
 data Entry {
   filePath :: !TarPath
   fileMode :: !FileMode
   ...
 }
 | {
    blah :: Whatever
 }
 }}}

-- 
Ticket URL: <http://trac.haskell.org/haddock/ticket/3#comment:3>
haddock <http://www.haskell.org/haddock>
Haddock, The Haskell Documentation Tool