From fc2cfd2760f995b796936cb23d86fd7dbc6628dd Mon Sep 17 00:00:00 2001 From: simonmar Date: Fri, 4 Feb 2005 12:40:02 +0000 Subject: [haddock @ 2005-02-04 12:40:02 by simonmar] Update the documentation w.r.t. home modules and the not-home attribute. --- doc/haddock.xml | 112 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 82 insertions(+), 30 deletions(-) diff --git a/doc/haddock.xml b/doc/haddock.xml index df1dc4a7..b4464720 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -639,6 +639,34 @@ module is shown in the right-hand column. + + + + + + + + + Causes Haddock to behaves as if every module has the + ignore-exports attribute (). This might be useful for + generating implementation documentation rather than interface + documetnation, for example. + + + + + + + +  module + + + Causes Haddock to behaves as if module + module has the hide + atribute. (). + +
@@ -1063,7 +1091,7 @@ module Foo (
-
+
Hyperlinking and re-exported entities When Haddock renders a type in the generated @@ -1096,40 +1124,50 @@ import B Module A exports a datatype T. Module B imports A and exports a function f - whose type refers to T: the hyperlink in - f's signature will point to the definition of - T in the documentation for module - A. - - Now, module C exports both - T and f. We have a choice - about where to point the hyperlink to T in - f's type: either the definition exported by - module C or the definition exported by module - A. Haddock takes the view that in this case - pointing to the definition in C is better, - because the programmer might not wish to expose - A to the programmer at all: - A might be a module internal to the - implementation of the library in which C is - the external interface, so linking to definitions in the current - module is preferrable over an imported module. - - 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 + whose type refers to T. Also, both + T and f are re-exported from + module C. + + Haddock takes the view that each entity has a + home module; that is, the module that the library + designer would most like to direct the user to, to find the + documentation for that entity. So, Haddock makes all links to an entity + point to the home module. The one exception is when the entity is also + exported by the current module: Haddock makes a local link if it + can. + + How is the home module for an entity determined? + Haddock uses the following rules: + - the current module, if the current module exports the - relevant definition, or + If modules A and B both export the entity, and module A imports + (directly or indirectly) module B, then B is preferred. - 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. + A module with the hide attribute is never + chosen as the home. + + + A module with the not-home atribute is only + chosen if there are no other modules to choose. + + If multiple modules fit the criteria, then one is chosen at + random. If no modules fit the criteria (because the candidates are all + hidden), then Haddock will issue a warning for each reference to an + entity without a home. + + In the example above, module A is chosen as the + home for T because it does not import any other + module that exports T. The link from + f's + type in module B will therefore point to + A.T. However, C also exports + T and f, and the link from + f's type in C will therefore + point locally to C.T.
@@ -1180,7 +1218,7 @@ module A where - hide + ignore-exports ignore-exports @@ -1190,7 +1228,21 @@ module A where given in the body of the module. + + + + not-home + + + + Indicates that the current module should not be considered to + be the home module for each entity it exports, + unless that entity is not exported from any other module. See + for more details. + + +
-- cgit v1.2.3