aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSimon Marlow <simonmar@microsoft.com>2006-05-08 08:28:53 +0000
committerSimon Marlow <simonmar@microsoft.com>2006-05-08 08:28:53 +0000
commit748b707883060c25e25c4d7e0f8a21c796b851fb (patch)
tree0924f100bde6168dc247034a1b3037f55d499b00 /doc
parentdab9fe7a3df480805508eaccfb7383aa6264d612 (diff)
add section about deriving
Diffstat (limited to 'doc')
-rw-r--r--doc/haddock.xml32
1 files changed, 32 insertions, 0 deletions
diff --git a/doc/haddock.xml b/doc/haddock.xml
index 750cc444..87aa8c43 100644
--- a/doc/haddock.xml
+++ b/doc/haddock.xml
@@ -1306,6 +1306,38 @@ import B
point locally to <literal>C.T</literal>.</para>
</section>
+ <section id="deriving">
+ <title>Derived instances</title>
+
+ <para>The <literal>deriving</literal> keyword in Haskell
+ presents a small problem for Haddock. Lacking a full type
+ system, Haddock has to figure out what the shape of the derived
+ instance is. There is currently a partial implementation of
+ this, but for some data types Haddock can't determine the shape
+ of the derived instance, and you see something like
+ &ldquo;???&rdquo; in the documentation.</para>
+
+ <para>One workaround for this is to use CPP (<xref linkend="cpp"
+ />) to give Haddock explicit instance headers. Here is an
+ example from the OpenGL library:</para>
+
+<programlisting>
+data VertexArrayDescriptor a =
+ VertexArrayDescriptor !NumComponents !DataType !Stride !(Ptr a)
+#ifdef __HADDOCK__
+-- Help Haddock a bit, because it doesn't do any instance inference.
+instance Eq (VertexArrayDescriptor a)
+instance Ord (VertexArrayDescriptor a)
+instance Show (VertexArrayDescriptor a)
+#else
+ deriving ( Eq, Ord, Show )
+#endif
+</programlisting>
+
+ <para>As a rule of thumb, try <literal>deriving</literal> first,
+ and if that doesn't work then use the above workaround.</para>
+ </section>
+
<section id="module-attributes">
<title>Module Attributes</title>