Haddock - Trying to use named block while documenting class method

Question

Is it possible to document a class method with Haddock and query pieces of documentation in the instance declaration code?

For exemple, I would like the class documented like this :

class ModifMATH a  where
  -- | Explanations of simpMath method.
  -- 
  --
  -- $part1
  -- $part2
  -- $part3      
  simpMath :: a -> a

and the instance documented like this :

instance ModifMATH MathExpress where
  -- $part1 a piece of explanation
  simpMath (MathDouble n)            = ...   

  -- $part2 another explanation 
  simpMath (MathMult a b)   = ...

  -- $part3 end of explanations 
  simpMath (MathAdd a b)   =  ...

and get the html Haddock documentation look like this (sorry i have no image) :

class ModifMATH a where
   Methods
      simpMath :: a -> a
         Explanations of simpMath method.
         a piece of explanation
         another explanation
         end of explanations

This organization of documentation would be more readable and extensible when adding patterns in the instance while keeping the whole method documentation in a stand-alone paragraph. Is it possible?

I'm using Haddock version 2.10.0. on Debian 7.0.

Thank you for your help.

score 2 · Accepted Answer · edited Jun 20 '20 at 09:12

No, it's not possible to split up documentation like this.

The only place where it was possible to more or less do this was in case of some questionable use of record fields but does not apply here and we have changed this behaviour in 2.14.x.

Perhaps you could use a definition list to try and get some natural split in your documentation. For example, something like

class ModifMATH a  where
  -- | Explanations of simpMath method.
  -- 
  -- [MathDouble case] $part1
  --
  -- [MathMult case] $part2
  --
  -- [MathAdd case] $part3      
  simpMath :: a -> a

Please note that the docs refer to the 2.14.x version which is quite a a bit newer than what you're using so for example those newlines between each definition list are necessary.

It should look more or less like:

_{(source: fuuzetsu.co.uk)}

You can go multi-line if needed, refer to the docs.

Haddock - Trying to use named block while documenting class method

1 Answers1