[commit: haddock] alexbiehl-patch-1, ghc-head, ghc-head1, headdock-library-1.4.5, ie_avails, master, pr-filter-maps, pr/cabal-desc, travis, v2.18, wip/remove-frames, wip/remove-frames1, wip/revert-ttg-2017-11-20, wip/ttg-2017-10-13, wip/ttg-2017-10-31, wip/ttg-2017-11-06, wip/ttg2-2017-11-10, wip/ttg3-2017-11-12, wip/ttg4-constraints-2017-11-13: More docs. (f65966b)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/haddock

On branches: alexbiehl-patch-1,ghc-head,ghc-head1,headdock-library-1.4.5,ie_avails,master,pr-filter-maps,pr/cabal-desc,travis,v2.18,wip/remove-frames,wip/remove-frames1,wip/revert-ttg-2017-11-20,wip/ttg-2017-10-13,wip/ttg-2017-10-31,wip/ttg-2017-11-06,wip/ttg2-2017-11-10,wip/ttg3-2017-11-12,wip/ttg4-constraints-2017-11-13
Link       : http://git.haskell.org/haddock.git/commitdiff/f65966b2febe36c8aae8ebee13d3f12a63479e65

>---------------------------------------------------------------

commit f65966b2febe36c8aae8ebee13d3f12a63479e65
Author: Edward Z. Yang <ezyang at cs.stanford.edu>
Date:   Mon Mar 13 15:25:09 2017 -0700

    More docs.
    
    Signed-off-by: Edward Z. Yang <ezyang at cs.stanford.edu>
    (cherry picked from commit 3d77b373dd5807d5d956719dd7c849a11534fa6a)


>---------------------------------------------------------------

f65966b2febe36c8aae8ebee13d3f12a63479e65
 haddock-api/src/Haddock/Interface/Create.hs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/haddock-api/src/Haddock/Interface/Create.hs b/haddock-api/src/Haddock/Interface/Create.hs
index 502d659..f1043c0 100644
--- a/haddock-api/src/Haddock/Interface/Create.hs
+++ b/haddock-api/src/Haddock/Interface/Create.hs
@@ -92,6 +92,7 @@ createInterface tm flags modMap instIfaceMap = do
         | Flag_IgnoreAllExports `elem` flags = OptIgnoreExports : opts0
         | otherwise = opts0
 
+  -- Process the top-level module header documentation.
   (!info, mbDoc) <- liftErrMsg $ processModuleHeader dflags gre safety mayDocHeader
 
   let declsWithDocs = topDecls group_
@@ -114,6 +115,8 @@ createInterface tm flags modMap instIfaceMap = do
 
   let allWarnings = M.unions (warningMap : map ifaceWarningMap (M.elems modMap))
 
+  -- The MAIN functionality: compute the export items which will
+  -- each be the actual documentation of this module.
   exportItems <- mkExportItems modMap mdl sem_mdl allWarnings gre exportedNames decls
                    maps fixMap splices exports instIfaceMap dflags
 
@@ -352,6 +355,8 @@ mkMaps dflags gre instances decls =
 
 
 -- | Get all subordinate declarations inside a declaration, and their docs.
+-- A subordinate declaration is something like the associate type or data
+-- family of a type class.
 subordinates :: InstMap -> HsDecl Name -> [(Name, [HsDocString], Map Int HsDocString)]
 subordinates instMap decl = case decl of
   InstD (ClsInstD d) -> do