Sophie: haddock-0.6-1mdk i586

haddock-0.6-1mdk.i586.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Hyperlinking and re-exported entities</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Haddock User Guide"
HREF="haddock.html"><LINK
REL="UP"
TITLE="Documentation and Markup"
HREF="markup.html"><LINK
REL="PREVIOUS"
TITLE="Named chunks of documentation"
HREF="x516.html"><LINK
REL="NEXT"
TITLE="Module Attributes"
HREF="module-attributes.html"></HEAD
><BODY
CLASS="SECTION"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Haddock User Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x516.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 3. Documentation and Markup</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="module-attributes.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECTION"
><H1
CLASS="SECTION"
><A
NAME="AEN531"
>3.6. Hyperlinking and re-exported entities</A
></H1
><P
>When Haddock renders a type in the generated
      documentation, it hyperlinks all the type constructors and class
      names in that type to their respective definitions.  But for a
      given type constructor or class there may be several modules
      re-exporting it, and therefore several modules whose
      documentation contains the definition of that type or class
      (possibly including the current module!) so which one do we link
      to?</P
><P
>Let's look at an example.  Suppose we have three modules
      <TT
CLASS="LITERAL"
>A</TT
>, <TT
CLASS="LITERAL"
>B</TT
> and
      <TT
CLASS="LITERAL"
>C</TT
> defined as follows:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>module A (T) where
data T a = C a

module B (f) where
import A
f :: T Int -&#62; Int
f (C i) = i

module C (T, f) where
import A
import B</PRE
></TD
></TR
></TABLE
><P
>Module <TT
CLASS="LITERAL"
>A</TT
> exports a datatype
      <TT
CLASS="LITERAL"
>T</TT
>.  Module <TT
CLASS="LITERAL"
>B</TT
> imports
      <TT
CLASS="LITERAL"
>A</TT
> and exports a function <TT
CLASS="LITERAL"
>f</TT
>
      whose type refers to <TT
CLASS="LITERAL"
>T</TT
>: the hyperlink in
      <TT
CLASS="LITERAL"
>f</TT
>'s signature will point to the definition of
      <TT
CLASS="LITERAL"
>T</TT
> in the documentation for module
      <TT
CLASS="LITERAL"
>A</TT
>.</P
><P
>Now, module <TT
CLASS="LITERAL"
>C</TT
> exports both
      <TT
CLASS="LITERAL"
>T</TT
> and <TT
CLASS="LITERAL"
>f</TT
>.  We have a choice
      about where to point the hyperlink to <TT
CLASS="LITERAL"
>T</TT
> in
      <TT
CLASS="LITERAL"
>f</TT
>'s type: either the definition exported by
      module <TT
CLASS="LITERAL"
>C</TT
> or the definition exported by module
      <TT
CLASS="LITERAL"
>A</TT
>.  Haddock takes the view that in this case
      pointing to the definition in <TT
CLASS="LITERAL"
>C</TT
> is better,
      because the programmer might not wish to expose
      <TT
CLASS="LITERAL"
>A</TT
> to the programmer at all:
      <TT
CLASS="LITERAL"
>A</TT
> might be a module internal to the
      implementation of the library in which <TT
CLASS="LITERAL"
>C</TT
> is
      the external interface, so linking to definitions in the current
      module is preferrable over an imported module.</P
><P
>The general rule is this: when attempting to link an
      instance of a type constructor or class to its definition, the
      link is made to</P
><P
></P
><UL
><LI
><P
>the current module, if the current module exports the
	  relevant definition, or</P
></LI
><LI
><P
>the module that the entity was imported from,
	  otherwise.  If the entity was imported via multiple routes,
	  then Haddock picks the module listed earliest in the imports
	  of the current module.</P
></LI
></UL
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x516.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="haddock.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="module-attributes.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Named chunks of documentation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="markup.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Module Attributes</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>