Document `filter` parameter of `with_options`

[MisterDA]

The parameter ?filter:( name:string -> index:int -> [ `Run | `Skip ] ) isn't documented, and I don't understand well whether it's referring to the name of the test (as a list of test cases) or a test case. I suppose it's a test, and the index refers to the index of a test case in a test.

[craigfe]

I suppose it's a test, and the index refers to the index of a test case in a test.

Indeed 🙂 The parameter exists in order to support the test subcommand of Alcotest binaries, which runs a regex over name and checks that index belongs to a given set:

SYNOPSIS
       test.exe test [OPTION]... [NAME_REGEX] [TESTCASES]

ARGUMENTS
       NAME_REGEX
           A regular expression matching the names of tests to run

       TESTCASES
           A comma-separated list of test case numbers (and ranges of numbers)
           to run, e.g: '4,6-10,19'. When specifying ranges, both '-' and '..'
           are accepted as valid separators.

A contribution to improve the API doc is very welcome. Filtering test cases will hopefully become clearer (or at least less arbitrary) with the introduction of the nestable test API.