damldocs: Show generic template args and context. (#2181)

* Collect generic template args and context

* Revert template anchor change (keep it separate)

* Output generic template args and context in Rst docs

* Add template args and context in Md output

compiler/damlc/daml-doc/src/DA/Daml/Doc/HaddockParse.hs

@@ -38,6 +38,7 @@ import qualified Data.Map.Strict as MS
 import qualified Data.Set as Set
 import qualified Data.Text                                 as T
 import           Data.Tuple.Extra                          (second)
+import Data.Either
 
 -- | Parse, and process documentation in, a dependency graph of modules.
 mkDocs
@@ -59,21 +60,25 @@ mkDocs opts fp = do
     mkModuleDocs tmr =
         let ctx@DocCtx{..} = buildDocCtx (Service.tmrModule tmr)
             typeMap = MS.fromList $ mapMaybe (getTypeDocs ctx) dc_decls
-            fctDocs = mapMaybe (getFctDocs ctx) dc_decls
-            clsDocs = mapMaybe (getClsDocs ctx) dc_decls
-            tmplDocs = getTemplateDocs ctx typeMap
-            adtDocs
+            classDocs = mapMaybe (getClsDocs ctx) dc_decls
+
+            (md_classes, templateInstanceClasses) =
+                partitionEithers . flip map classDocs $ \classDoc ->
+                    case stripInstanceSuffix (cl_name classDoc) of
+                        Nothing -> Left classDoc
+                        Just templateName -> Right (templateName, classDoc)
+            templateInstanceMap = MS.fromList templateInstanceClasses
+
+            md_name = dc_modname
+            md_anchor = Just (moduleAnchor md_name)
+            md_descr = modDoc dc_tcmod
+            md_templates = getTemplateDocs ctx typeMap templateInstanceMap
+            md_functions = mapMaybe (getFctDocs ctx) dc_decls
+            md_adts
                 = MS.elems . MS.withoutKeys typeMap . Set.unions
                 $ dc_templates : MS.keysSet dc_templateInstances : MS.elems dc_choices
-        in ModuleDoc
-            { md_anchor = Just (moduleAnchor dc_modname)
-            , md_name = dc_modname
-            , md_descr = modDoc dc_tcmod
-            , md_adts = adtDocs
-            , md_templates = tmplDocs
-            , md_functions = fctDocs
-            , md_classes = clsDocs
-            }
+
+        in ModuleDoc {..}
 
 -- | Return the names for a given signature.
 -- Equivalent of Haddock’s Haddock.GhcUtils.sigNameNoLoc.
@@ -253,8 +258,6 @@ getClsDocs ctx@DocCtx{..} (DeclData (L _ (TyClD _ c@ClassDecl{..})) docs) = do
             let theta = classSCTheta cls
             guard (notNull theta)
             Just (TypeTuple $ map (typeToType ctx) theta)
-    guard (isNothing (stripInstanceSuffix cl_name))
-       -- don't generate docs for template instance classes
     Just ClassDoc {..}
   where
     f :: LSig GhcPs -> [FunctionDoc]
@@ -318,15 +321,23 @@ getTypeDocs ctx@DocCtx{..} (DeclData (L _ (TyClD _ decl)) doc)
     fieldDoc (_, L _ XConDeclField{}) = Nothing
 getTypeDocs _ _other = Nothing
 
-getTemplateDocs :: DocCtx -> MS.Map Typename ADTDoc -> [TemplateDoc]
-getTemplateDocs DocCtx{..} typeMap = map mkTemplateDoc $ Set.toList dc_templates
+-- | Build template docs up from ADT and class docs.
+getTemplateDocs ::
+    DocCtx
+    -> MS.Map Typename ADTDoc -- ^ maps template names to their ADT docs
+    -> MS.Map Typename ClassDoc -- ^ maps template names to their template instance class docs
+    -> [TemplateDoc]
+getTemplateDocs DocCtx{..} typeMap templateInstanceMap =
+    map mkTemplateDoc $ Set.toList dc_templates
   where
     -- The following functions use the type map and choice map in scope, so
     -- defined internally, and not expected to fail on consistent arguments.
     mkTemplateDoc :: Typename -> TemplateDoc
     mkTemplateDoc name = TemplateDoc
-      { td_anchor = Just $ templateAnchor dc_modname (ad_name tmplADT)
+      { td_anchor = Just $ templateAnchor dc_modname name
       , td_name = ad_name tmplADT
+      , td_args = ad_args tmplADT
+      , td_super = cl_super =<< MS.lookup name templateInstanceMap
       , td_descr = ad_descr tmplADT
       , td_payload = getFields tmplADT
       -- assumes exactly one record constructor (syntactic, template syntax)

compiler/damlc/daml-doc/src/DA/Daml/Doc/Render/Markdown.hs

@@ -62,8 +62,14 @@ renderSimpleMD ModuleDoc{..} = mconcat
 
 
 tmpl2md :: TemplateDoc -> RenderOut
-tmpl2md TemplateDoc{..} = mconcat
-    [ renderAnchorInfix "### " td_anchor ("Template " <> escapeMd (unTypename td_name))
+tmpl2md TemplateDoc{..} = withAnchorTag td_anchor $ \tag -> mconcat
+    [ renderLineDep $ \env -> T.concat
+        [ "### "
+        , tag
+        , "template "
+        , maybe "" ((<> " => ") . type2md env) td_super
+        , escapeMd . T.unwords $ unTypename td_name : td_args
+        ]
     , renderDocText td_descr
     , fieldTable td_payload
     , if null td_choices

compiler/damlc/daml-doc/src/DA/Daml/Doc/Render/Rst.hs

@@ -88,7 +88,11 @@ renderSimpleRst ModuleDoc{..} = mconcat $
 tmpl2rst :: TemplateDoc -> RenderOut
 tmpl2rst TemplateDoc{..} = mconcat $
   [ renderAnchor td_anchor
-  , renderLine $ "template " <> enclosedIn "**" (unTypename td_name)
+  , renderLineDep $ \env -> T.concat
+      [ "template "
+      , maybe "" ((<> " => ") . type2rst env) td_super
+      , T.unwords (enclosedIn "**" (unTypename td_name) : td_args)
+      ]
   , maybe mempty ((renderLine "" <>) . renderIndent 2 . renderDocText) td_descr
   , renderLine ""
   , renderIndent 2 (fieldTable td_payload)

compiler/damlc/daml-doc/src/DA/Daml/Doc/Types.hs

@@ -64,6 +64,8 @@ data ModuleDoc = ModuleDoc
 data TemplateDoc = TemplateDoc
   { td_anchor  :: Maybe Anchor
   , td_name    :: Typename
+  , td_super   :: Maybe Type
+  , td_args    :: [Text]
   , td_descr   :: Maybe DocText
   , td_payload :: [FieldDoc]
   , td_choices :: [ChoiceDoc]

compiler/damlc/tests/daml-test-files/Iou_template.EXPECTED.md

@@ -2,7 +2,7 @@
 
 ## Templates
 
-### <a name="template-ioutemplate-iou-32396"></a>Template Iou
+### <a name="template-ioutemplate-iou-32396"></a>template Iou
 
 | Field      | Type/Description |
 | :--------- | :----------------

compiler/damlc/tests/daml-test-files/ProposalDSL.EXPECTED.md

@@ -0,0 +1,22 @@
+# <a name="module-proposaldsl-55246"></a>Module ProposalDSL
+
+## Templates
+
+### <a name="template-proposaldsl-proposal-62786"></a>template (Template t) => Proposal t
+
+| Field     | Type/Description |
+| :-------- | :----------------
+| asset     | t |
+| receivers | \[Party\] |
+| name      | Text |
+
+
+Choices:
+
+* Accept
+  
+  (no fields)
+* External:Archive
+  
+  (no fields)
+

compiler/damlc/tests/daml-test-files/ProposalDSL.EXPECTED.rst

@@ -10,7 +10,7 @@ Templates
 
 .. _template-proposaldsl-proposal-62786:
 
-template **Proposal**
+template (Template t) => **Proposal** t
 
   .. list-table::
      :widths: 15 10 30