From 69422327f934c04795bd9d3438847babe1cc785d Mon Sep 17 00:00:00 2001 From: simonmar Date: Mon, 10 Nov 2003 14:41:06 +0000 Subject: [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. --- src/HaddockHtml.hs | 14 +++++++++----- src/HaddockRename.hs | 4 ++++ src/HaddockTypes.hs | 6 ++++++ src/Main.hs | 37 +++++++++++++++++++++++++++++-------- 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. -- cgit v1.2.3