Executable documentation examples?

Ecosystem
,
1

In Rust, the standard test harness will extract snippets from the documentation and run them as tests, e.g. the following documentation will fail the test suite:

/**
 * Add two values
 *
 *  ```
 *   assert_eq!(add(2, 2), 5)
 *  ```
 */
fn add(x: i32, y: i32) -> i32 {
   x + y
}

(with some extensions, this also works for code in .md files)

This is quite convenient to ensure that the documentation is reasonably up-to-date.

Is there any equivalent in the modern OCaml ecosystem?

2

Hi @Yoric,

If you are happy to use dune as your build system, then you can add a mdx stanza for “executable documentation” using ocaml-mdx. This will work for markdown files, .mld documentation files and .mli interface files. Note that mdx becomes a with-test dependency of your project if you do this.