docs: variadic functions clarification

[lorenarosati]

The number of arguments required for variadic functions should be the minimum, not the minimum + 1. This is stated in some areas of the website, but other areas contradict this. The website should have consistent messaging regarding the rules for variadic functions.

---

This change is 

[github-actions]

ACTION NEEDED

Substrait follows the Conventional Commits
specification for
release automation.

The PR title and description are used as the merge commit message. Please update your PR title and description to match the specification.

[EpsilonPrime]

So the difference between the last parameter being optional and not optional is no longer relevant? The previous definition basically comes down to two rules:

1. If the function is variadic then it allows the last argument to be repeated multiple times (i.e. maximum is increased.
2. If the last argument is optional, then the last argument can be omitted (minimum is now 0).

[lorenarosati]

This page was inconsistent with other explanations, which implied that the argument can be specified zero or more times if the minimum is zero. If the explanation with the last parameter being optional is the definition that we want, then other areas should be changed to explain that the argument can be specified one or more times if the minimum is zero. Should I revert to the previous definition and make that consistent instead? @vbarua

[vbarua]

@EpsilonPrime When you say

So the difference between the last parameter being optional

what do you mean? Are you talking about the last argument being nullable? That's not the same as being allowed to omit it entirely.

Thinking about this from a function resolution perspective, I wonder if it makes sense to require at least one argument for all variadic functions. You could imagine having something like:

-
    name: concat_to_string
      - args:
          - value: "varchar<L1>"
            name: "input"
        variadic:
          min: 0
        return: "string"
      - args:
          - value: "string"
            name: "input"
        variadic:
          min: 0
        return: "string"

and if the function call doesn't have any arguments you can't distinguish between the 2. If folks end up wanting the 0 argument variant, they could define it explicitly like:

-
    name: concat_to_string
        return: "string"

In the core spec right now, all variadic functions but and and or require at least 1 argument.

You could make the case that producers should simplify and() directly to true and or() directly to false.