What style of code comments are required for daml damlc docs?

Questions
1

Running daml damlc docs on the following does not copy the comments to the generated docs:

-- an asset is a thing that can be owned by a user
template Asset
  with
    -- the issuer of the asset
    issuer : Party
    owner  : Party
    name   : Text

What comment style is expected by the daml damlc docs (aka, “damldocs”) command?

2

The daml damlc docs command is looking for Haddock-style annotations. However, see this caveat.

For the following:

-- | an asset is a thing that can be owned by a user
template Asset
  with
    issuer : Party
      -- ^ the issuer of the asset
    owner  : Party
    name   : Text

The command:

daml damlc docs -o docs --doc-ext md daml/Main.daml

Generates:

image
image351×256 11.4 KB

You can see examples in the Daml Standard Library and the Splice code base. Finally, there is a ticket to document the docs function.