[haddock @ 2003-11-10 14:41:05 by simonmar]

Re-exporting names from a different package is problematic, because we
don't have access to the full documentation for the entity.  Currently
Haddock just ignores entities with no documentation, but this results
in bogus-looking empty documentation for many of the modules in the
haskell98 package.  So:

  - the documentation will now just list the name, as a link
    pointing to the location of the actual documentation.

  - now we don't attempt to link to these re-exported entities if
    they are referred to by the current module.

Additionally:

  - If there is no documentation in the current module, include
    just the Synopsis section (rather than just the documentation
    section, as it was before).  This just looks nicer and was on
    the TODO list.

4 files changed, 48 insertions, 13 deletions

diff --git a/src/HaddockHtml.hs b/src/HaddockHtml.hs
index 9c3be7b3..6a9f193e 100644
--- a/src/HaddockHtml.hs
+++ b/src/HaddockHtml.hs
@@ -383,6 +383,7 @@ ifaceToHtml _ iface
 	exports = numberSectionHeadings (iface_exports iface)
 
 	has_doc (ExportDecl _ d _) = isJust (declDoc d)
+	has_doc (ExportNoDecl _ _ _) = False
 	has_doc (ExportModule _) = False
 	has_doc _ = True
 
@@ -399,8 +400,6 @@ ifaceToHtml _ iface
 
 	-- omit the synopsis if there are no documentation annotations at all
 	synopsis
-	  | no_doc_at_all = Html.emptyTable
-	  | otherwise
 	  = (tda [theclass "section1"] << toHtml "Synopsis") </>
 	    s15 </>
             (tda [theclass "body"] << vanillaTable <<
@@ -411,14 +410,15 @@ ifaceToHtml _ iface
 	-- if the documentation doesn't begin with a section header, then
 	-- add one ("Documentation").
 	maybe_doc_hdr
-	     | not (no_doc_at_all) = 
+	     | no_doc_at_all  = Html.emptyTable
+	     | otherwise = 
 		case exports of
 		   [] -> Html.emptyTable
 		   ExportGroup _ _ _ : _ -> Html.emptyTable
 		   _ -> tda [ theclass "section1" ] << toHtml "Documentation"
-	     | otherwise  = Html.emptyTable
 
-	bdy = map (processExport False) exports
+	bdy  | no_doc_at_all = []
+	     | otherwise     = map (processExport False) exports
 
 ppModuleContents :: [ExportItem] -> HtmlTable
 ppModuleContents exports
@@ -459,6 +459,10 @@ processExport _ (ExportGroup lev id0 doc)
   = ppDocGroup lev (namedAnchor id0 << docToHtml doc)
 processExport summary (ExportDecl x decl insts)
   = doDecl summary x decl insts
+processExport summmary (ExportNoDecl _ y [])
+  = declBox (ppHsQName y)
+processExport summmary (ExportNoDecl _ y subs)
+  = declBox (ppHsQName y <+> parenList (map ppHsQName subs))
 processExport _ (ExportDoc doc)
   = docBox (docToHtml doc)
 processExport _ (ExportModule (Module mdl))
diff --git a/src/HaddockRename.hs b/src/HaddockRename.hs
index ad90c1a2..86e74490 100644
--- a/src/HaddockRename.hs
+++ b/src/HaddockRename.hs
@@ -265,6 +265,10 @@ renameExportItems items = mapM rn items
 	   = do decl <- renameDecl decl0
 		mapM renameInstHead insts
 		return (ExportDecl x decl insts)
+	rn (ExportNoDecl x y subs)
+	   = do y' <- lookupRn id y
+	        subs' <- mapM (lookupRn id) subs
+		return (ExportNoDecl x y' subs')
 	rn (ExportDoc doc0)
 	   = do doc <- renameDoc doc0
 		return (ExportDoc doc)
diff --git a/src/HaddockTypes.hs b/src/HaddockTypes.hs
index 174b13a2..5430060c 100644
--- a/src/HaddockTypes.hs
+++ b/src/HaddockTypes.hs
@@ -83,6 +83,12 @@ data ExportItem
 	HsDecl		-- a declaration (with doc annotations)
 	[InstHead]	-- instances relevant to this declaration
 
+  | ExportNoDecl	-- an exported entity for which we have no documentation
+			-- (perhaps becuase it resides in another package)
+	HsQName		-- the original name
+	HsQName		-- where to link to
+	[HsQName]	-- subordinate names
+
   | ExportGroup		-- a section heading
 	Int		-- section level (1, 2, 3, ... )
 	String		-- section "id" (for hyperlinks)
diff --git a/src/Main.hs b/src/Main.hs
index 0fcd44d6..1c2674bf 100644
--- a/src/Main.hs
+++ b/src/Main.hs
@@ -400,6 +400,11 @@ mkInterface no_implicit_prelude verbose mod_map filename package
 
      -- build the import env, which maps original names to import names
      local_import_env = listToFM (zip qual_local_names qual_local_names)
+
+     -- find the names exported by this module that other modules should *not*
+     -- link to (and point them to where they should).
+     reexports = getReExports mdl mod_map orig_exports
+
      import_env = local_import_env `plusFM`
 		   buildImportEnv mod_map mdl exported_visible_names 
 			implicit_imps
@@ -433,10 +438,6 @@ mkInterface no_implicit_prelude verbose mod_map filename package
 
      name_env = listToFM [ (nameOfQName n, n) | n <- exported_names ]
 
-     -- find the names exported by this module that other modules should *not*
-     -- link to (and point them to where they should).
-     reexports = getReExports mdl mod_map orig_exports
-
   let
      (orig_module_doc, missing_names4)
         = runRnFM orig_env (renameMaybeDoc maybe_doc)
@@ -600,7 +601,11 @@ mkExportItems mod_map this_mod orig_env decl_map sub_map decls
 	| Just decl <- findDecl t
 	= return [ ExportDecl t (restrictTo subs (extractDecl x mdl decl)) [] ]
 	| otherwise
-	= return []
+	= return [ ExportNoDecl t t (map (Qual mdl) subs) ]
+	-- can't find the decl (it might be from another package), but let's
+	-- list the entity anyway.  Later on, the renamer will change the
+	-- orig name into the import name, so we get a proper link to
+	-- the doc for this entity.
 	where 
 	      subs = 
 		case mb_subs of
@@ -782,7 +787,21 @@ exportedNames mdl mod_map local_names orig_env sub_map maybe_exps opts
 		| otherwise -> return []
 	    Nothing
 		-> return []  -- we already emitted a warning above
-    _ -> extract e
+
+    -- remaining cases: we have to catch names which are reexported from
+    -- here, but for which we have no documentation, perhaps because they
+    -- are from another package.  We have to do this by looking for
+    -- the declaration in the other module.
+    _ -> do xs <- extract e
+	    return (filter is_documented_here xs)
+
+  is_documented_here (UnQual _) = False
+  is_documented_here (Qual m n)
+    | m == mdl  = True -- well, it's not documented anywhere else!
+    | otherwise =
+	case lookupFM mod_map m of
+	  Nothing -> False
+	  Just iface -> isJust (lookupFM (iface_decls iface) n)
 
 exportModuleMissingErr this mdl 
   = ["Warning: in export list of " ++ show this
@@ -863,7 +882,9 @@ buildOrigEnv this_mdl verbose mod_map imp_decls
 -- module to the qualified name that we want to link to in the
 -- documentation.
 
-buildImportEnv :: ModuleMap -> Module -> [HsQName] -> [HsImportDecl]
+buildImportEnv :: ModuleMap -> Module
+        -> [HsQName]	   -- a list of names exported from here *with docs*
+	-> [HsImportDecl]  -- the import decls
 	-> FiniteMap HsQName HsQName
 buildImportEnv mod_map this_mod exported_names imp_decls
   = foldr plusFM emptyFM (map build imp_decls)
@@ -879,7 +900,7 @@ buildImportEnv mod_map this_mod exported_names imp_decls
 	      import_map (nm,qnm) = (qnm, maps_to)
  	       where 
 		maps_to
-		 -- we re-export it: just link to this module
+		 -- we re-export it, with docs
 		 | qnm `elem` exported_names = Qual this_mod nm
 		 -- re-exported from the other module, but not documented there:
 		 -- find the right place using the iface_reexported environment.