How to reduce documentation duplication using Haddock

4
votes

I have two very similar functions and both need exactly the same documentation. Is there a way in Haddock to avoid comment duplication?

I could not find description of this feature in Haddock documentation, but I guess there is a way to do so.

For instance in Javadoc there is {@inheritDoc} and @see SomeClass#someMethod(). What about Haddock?

1
haskellhaddock
I thought you could use Named chunks of documentation ( haskell.org/haddock/doc/html/ch03s05.html ) for that (I never did, but I sometimes see haddock complain when I comment out a dollar, as in "-- $ foo"). You can define a name for a chunk, but appatently only use it in the export list, and it must be at the beginng of a comment. – d8d0d65b3f7cf42
If the functions are closely related it might be better to not duplicate the documentation, and instead refer the reader to the documentation for the other function. Then if they differ only by types the reader will see one description and two functions with slightly different type signatures. – Cirdec

1 Answers

2
votes

Unfortunately, it is not possible for function declarations to have reusable documentation with Haddock at the moment. Here is an issue tracking this.

The -- $chunk_name documentation chunk naming is only available for module documentation, i.e for the export section. This is only handy for moving documentation from the top of the module to the bottom to reduce the clutter.

Common workarounds for this problem are:

  • make sure the similar function is in scope an add this to documentation: -- | See `functionName`. OR -- | See 'functionName'.
  • or manually copy and paste documentation if it is small enough, similarly how it is done in bytestring and vector packages.