Procedure arity and documentation

[Zelphir Kaltstahl <zelphirkaltstahl@posteo.de>]

Hello Guile users!

Today I found the procedure `procedure-minimum-arity`, while tab-completing in
Geiser. I then looked for its documentation in the Guile manual, but could not
find anything about it. (help procedure-minimum-arity) shows:

~~~~
scheme@(guile-user)> (help procedure-minimum-arity)
`procedure-minimum-arity' is a procedure in the (guile) module.

- Scheme Procedure: procedure-minimum-arity proc
     Return the "minimum arity" of a procedure.

     If the procedure has only one arity, that arity is returned as a
     list of three values: the number of required arguments, the number
     of optional arguments, and a boolean indicating whether or not the
     procedure takes rest arguments.

     For a case-lambda procedure, the arity returned is the one with the
     lowest minimum number of arguments, and the highest maximum number
     of arguments.

     If it was not possible to determine the arity of the procedure,
     `#f' is returned.
~~~~

Which helps a lot. I could not understand the procedure's output before that.

Why is the procedure named "minimum", when it also gives the number of optional
arguments and whether it accepts rest arguments?

Is this procedure official API, or is it merely exposed and I should not be
using it?

I am currently reading a book, which uses MIT/GNU Scheme and there exist
`procedure-arity-min` and `procedure-arity-max`. If there is `min`, then I would
expect `max` to be also there. I was a bit confused with Guile only having
`minimum`, but `minimum` not actually being only the minimum, but also option
and rest, which enables one to calculate the maximum.

I also found that the following errors:

~~~~
scheme@(guile-user)> (import (system vm program))
scheme@(guile-user)> (arity:nreq (program-arities (lambda (a b) (+ a b))))
ice-9/boot-9.scm:1685:16: In procedure raise-exception:
Unbound variable: program-arities

Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.
~~~~

Although the manual says:

> The normal case is that a procedure has one arity. For example, (lambda (x)
x), takes one required argument, and that’s it. One could access that number of
required arguments via (arity:nreq (program-arities (lambda (x) x))). Similarly,
arity:nopt gets the number of optional arguments, and arity:rest? returns a true
value if the procedure has a rest arg.

-- https://www.gnu.org/software/guile/manual/guile.html#Compiled-Procedures

Is that a bug, or is it, because I am trying to use it in the REPL and there my
procedure is not compiled?

Best regards,
Zelphir

-- 
repositories: https://notabug.org/ZelphirKaltstahl