Syntax for custom matcher arguments is not documented

[glts]

On the topic of the "match" Funcref in {matcher}, the help :h vspec#customize_matcher() only states:

A |Funcref| to determine whether {actual} value matches to {expected} value. It takes 1 or more arguments.

The only examples of custom matchers in the help do not take any arguments. This leaves the syntax to be used undocumented.

• Is it :Expect x to_have_args [1, 2, 3], like for the built-in call()?
• Is it :Expect x to_have_args 1 2 3, like for :command, or in the shell?
• Is it :Expect x to_have_args 1, 2, 3? (Yes.)

Adding to this, I think it should also be documented that the arguments are implicitly a list. Consider this test:

function! ToBeInteger(actual, expected)
  return a:actual == a:expected
endfunction

call vspec#customize_matcher('to_be_int', {'match': function('ToBeInteger')})

describe 'vspec default failure message'
  it 'has undocumented representation'
    let fortytwo = 42
    Expect fortytwo to_be_int 43
  end
end

This yields a message stating 42 does not equal [43], which may be misleading.

not ok 1 - vspec default failure message has undocumented representation
# Expected fortytwo to_be_int 43
#       Actual value: 42
#     Expected value: [43]

[kana]

There is a hint in :help vspec-custom-matcher:

:Expect {actual} {custom-matcher} [{arg}, ...]

Here [...] denotes an optional part. But it's hard for new users to guess the right syntax, as you suggest. I'll add more examples later.

[...] This yields a message stating 42 does not equal [43], which may be misleading.

It is a separate issue. In that case, the meaning of "expected value" is varied for each custom matcher. It's not possible to output proper messages for all situations from vspec. So that it would be recommended to customize how to generate a failure message for the custom matcher. The problem is that the default message generator doesn't make a reasonable message for custom matchers.

[glts]

There is a hint in :help vspec-custom-matcher:

I completely overlooked this, sorry. Thank you for your work.