Haddock for daml?

Questions
1

Is there a tool like haddock that can generate documentation out of the DAML files?

1 Like
2

Hi @Jean_Safar, yes, there is! It’s what we use to generate the standard library documentation. This tool is still in development, so there isn’t official documentation. To use it, run:

daml damlc docs --output OUTPUT FILE1 FILE2 ... FILEN

where FILE1 FILE2 ... FILEN are the DAML source files you want to document, and OUTPUT is the output folder. You can see all the options with daml damlc docs --help.

To write docs in DAML, you insert Haddock-style comments. For example,

-- | Add three numbers.
sum3 : Int -> Int -> Int
sum3 a b c = a + b + c

The documentation is formatted according to Markdown syntax:

  • **text** for bold
  • [text](link) for links
  • `text` for code
4 Likes
4

Thanks. It seems I can only document this way the upper level of a template but neither the variables of the template nor its choices, for which I get :

parse error on input ‘-- |

1 Like
5

Indentation and use of that tool are a bit tricky as we’ve modified parser and desugarer somewhat. Take this example to see the types of thing you can annotate, and how:

module M where

-- | A data type
data Foo = Foo with
  baz : ()
    -- ^ baz as type unit

-- | A top level function
constu : ()  -> ()
constu = const ()

-- | My Template
template T
  with
    p : Party
      -- ^ a party
  where
    signatory p

    controller p can
      C : ()
        -- ^ Choice
        with
          f : ()
            -- ^ a field
        do
          return (fn f)
3 Likes