interfaces: doc generation for interface methods

This adds documentation generation for interface choices and methods. CHANGELOG_BEGIN CHANGELOG_END
digital-asset · Dec 15, 2021 · 28bad42 · 28bad42
1 parent 259be43
commit 28bad42
Show file tree

Hide file tree

Showing 9 changed files with 26 additions and 11 deletions.
diff --git a/bazel-haskell-deps.bzl b/bazel-haskell-deps.bzl
@@ -17,11 +17,11 @@ load("@os_info//:os_info.bzl", "is_linux", "is_windows")
 load("@dadew//:dadew.bzl", "dadew_tool_home")
 load("@rules_haskell//haskell:cabal.bzl", "stack_snapshot")
 
-GHC_LIB_REV = "082058690020994a0206c651e9ea52e8"
-GHC_LIB_SHA256 = "ad0c7159afba3c2db708bae9cdbbe516efd8d5c7461d3c6763843c7ddbd5493f"
+GHC_LIB_REV = "554b4766f022cd50224e49286e16e7aa"
+GHC_LIB_SHA256 = "cd63ef5f3a6b5808f1c0f20eb8609d54289b588942f7e675b35a0e6f3cb3fd39"
 GHC_LIB_VERSION = "8.8.1"
-GHC_LIB_PARSER_REV = "082058690020994a0206c651e9ea52e8"
-GHC_LIB_PARSER_SHA256 = "5b2d8f4d659dec67ab940e1fc6599e9b8425a4cbcf650de92116a26161d94e98"
+GHC_LIB_PARSER_REV = "554b4766f022cd50224e49286e16e7aa"
+GHC_LIB_PARSER_SHA256 = "b6171904951887642b438d5fbe555401cfe89b7be1f0ad5bff8c0a671ccfd4db"
 GHC_LIB_PARSER_VERSION = "8.8.1"
 GHCIDE_REV = "e04b5386b3741b839eb5c3d2a2586fd2aa97229c"
 GHCIDE_SHA256 = "1d27926e0ad3c2a9536f23b454875a385ecc766ae68ce48a0ec88d0867884b46"

diff --git a/ci/da-ghc-lib/compile.yml b/ci/da-ghc-lib/compile.yml
@@ -12,7 +12,7 @@ jobs:
   variables:
     ghc-lib-sha: '362d4f38a7ac10521393de9b7ad942a77a2605be'
     base-sha: '9c787d4d24f2b515934c8503ee2bbd7cfac4da20'
-    patches: '5d120ecc2ddb427b29d2364302245807a48a3976 833ca63be2ab14871874ccb6974921e8952802e9'
+    patches: '9256ae0b1c7ef5215474e2ffe748a7db64f00333 833ca63be2ab14871874ccb6974921e8952802e9'
     flavor: 'da-ghc-8.8.1'
   steps:
   - checkout: self

diff --git a/compiler/damlc/daml-doc/src/DA/Daml/Doc/Extract/Templates.hs b/compiler/damlc/daml-doc/src/DA/Daml/Doc/Extract/Templates.hs
@@ -27,6 +27,7 @@ import "ghc-lib-parser" Var (varType)
 import "ghc-lib-parser" CoreSyn (isOrphan)
 import "ghc-lib-parser" InstEnv
 import "ghc-lib-parser" OccName
+import "ghc-lib-parser" Id
 
 -- | Build template docs up from ADT and class docs.
 getTemplateDocs ::
@@ -50,7 +51,7 @@ getTemplateDocs DocCtx{..} typeMap templateImplementsMap =
       , td_impls =
           ImplDoc <$>
             Set.toList (MS.findWithDefault mempty name templateImplementsMap)
-      }
+     }
       where
         tmplADT = asADT typeMap name
         choices = Set.toList . fromMaybe Set.empty $ MS.lookup name dc_choices
@@ -188,17 +189,19 @@ dropParTy ty = ty
 stripInstanceSuffix :: Typename -> Maybe Typename
 stripInstanceSuffix (Typename t) = Typename <$> T.stripSuffix "Instance" t
 
--- | Get (normal) typeclass instances data. TODO: Correlate with
--- instance declarations via SrcSpan (like Haddock).
+-- | Get (normal) typeclass instances data.
 getInstanceDocs :: DocCtx -> ClsInst -> InstanceDoc
-getInstanceDocs ctx ClsInst{..} =
+getInstanceDocs ctx@DocCtx{dc_decls} ClsInst{..} =
     let ty = varType is_dfun
+        srcSpan = getLoc $ idName is_dfun
         modname = Modulename $ T.pack $ moduleNameString $ moduleName $ nameModule is_cls_nm
+        instDocMap = MS.fromList [(l, doc) | (DeclData (L l (InstD _x _i)) (Just doc)) <- dc_decls]
     in InstanceDoc
         { id_context = typeToContext ctx ty
         , id_module = modname
         , id_type = typeToType ctx ty
         , id_isOrphan = isOrphan is_orphan
+        , id_descr = MS.lookup srcSpan instDocMap
         }
 
 -- Utilities common to templates and interfaces

diff --git a/compiler/damlc/daml-doc/src/DA/Daml/Doc/Render/Output.hs b/compiler/damlc/daml-doc/src/DA/Daml/Doc/Render/Output.hs
@@ -103,6 +103,7 @@ instance RenderDoc ImplDoc where
 instance RenderDoc MethodDoc where
     renderDoc MethodDoc {..} = mconcat
       [ RenderParagraph $ RenderStrong ("Method " <> unTypename mtd_name <> " : ") <> renderType mtd_type
+      , renderDoc mtd_descr
       ]
 
 instance RenderDoc ChoiceDoc where

diff --git a/compiler/damlc/daml-doc/src/DA/Daml/Doc/Transform/Instances.hs b/compiler/damlc/daml-doc/src/DA/Daml/Doc/Transform/Instances.hs
@@ -81,13 +81,14 @@ distributeInstanceDocs opts docs =
     addIfaceMethods imap idoc = idoc
       { if_methods =
           [ MethodDoc{..}
-          | InstanceDoc {id_type, id_module} <-
+          | InstanceDoc {id_type, id_module, id_descr} <-
                 maybe [] Set.toList $ do
                   anchor <- if_anchor idoc
                   Map.lookup anchor imap
           , Just "HasMethod" == getTypeAppName id_type
           , "DA.Internal.Desugar" == id_module
           , Just [_if_name, TypeLit name, mtd_type] <- [getTypeAppArgs id_type]
           , let mtd_name = Typename $ T.dropEnd 1 $ T.drop 1 name -- drop enclosing double-quotes.
+          , let mtd_descr = id_descr
           ]
       }
diff --git a/compiler/damlc/daml-doc/src/DA/Daml/Doc/Types.hs b/compiler/damlc/daml-doc/src/DA/Daml/Doc/Types.hs
@@ -234,6 +234,7 @@ data ChoiceDoc = ChoiceDoc
 data MethodDoc = MethodDoc
   { mtd_name :: Typename
   , mtd_type :: Type
+  , mtd_descr :: Maybe DocText
   }
   deriving (Eq, Show, Generic)
 
@@ -264,6 +265,7 @@ data InstanceDoc = InstanceDoc
     , id_module :: Modulename
     , id_context :: Context
     , id_isOrphan :: Bool
+    , id_descr :: Maybe DocText
     } deriving (Eq, Ord, Show, Generic)
 
 -----------------------------------------------------

diff --git a/compiler/damlc/tests/daml-test-files/Interface.EXPECTED.md b/compiler/damlc/tests/daml-test-files/Interface.EXPECTED.md
@@ -36,6 +36,8 @@
 > 
 > * **Choice Split**
 >   
+>   An interface choice comment.
+>   
 >   | Field                                                                          | Type                                                                           | Description |
 >   | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | :---------- |
 >   | splitAmount                                                                    | [Int](https://docs.daml.com/daml/stdlib/Prelude.html#type-ghc-types-int-68728) | A choice field comment. |
@@ -49,6 +51,8 @@
 > * **Method getAmount : **[Int](https://docs.daml.com/daml/stdlib/Prelude.html#type-ghc-types-int-68728)
 > 
 > * **Method getOwner : **[Party](https://docs.daml.com/daml/stdlib/Prelude.html#type-da-internal-lf-party-50311)
+>   
+>   A method comment.
 > 
 > * **Method noopImpl : **() -\> [Update](https://docs.daml.com/daml/stdlib/Prelude.html#type-da-internal-lf-update-36457) ()
 > 

diff --git a/compiler/damlc/tests/daml-test-files/Interface.EXPECTED.rst b/compiler/damlc/tests/daml-test-files/Interface.EXPECTED.rst
@@ -69,6 +69,8 @@ Interfaces
 
   + **Choice Split**
 
+    An interface choice comment\.
+
     .. list-table::
        :widths: 15 10 30
        :header-rows: 1
@@ -96,6 +98,8 @@ Interfaces
   + **Method getAmount \: **`Int <https://docs.daml.com/daml/stdlib/Prelude.html#type-ghc-types-int-68728>`_
   
   + **Method getOwner \: **`Party <https://docs.daml.com/daml/stdlib/Prelude.html#type-da-internal-lf-party-50311>`_
+    
+    A method comment\.
 
   + **Method noopImpl \: **() \-\> `Update <https://docs.daml.com/daml/stdlib/Prelude.html#type-da-internal-lf-update-36457>`_ ()
   

diff --git a/compiler/damlc/tests/daml-test-files/Interface.daml b/compiler/damlc/tests/daml-test-files/Interface.daml
@@ -19,7 +19,7 @@ interface Token where
 
   ensure (getAmount this >= 0)
 
-  choice Split : (ContractId Token, ContractId Token)
+  choice Split : (ContractId Token, ContractId Token) -- ^ An interface choice comment.
     with
       splitAmount : Int -- ^ A choice field comment.
     controller getOwner this