bug#30145: [PATCH] doc: Document unspecified?.

[Mark H Weaver <mhw@netris.org>]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

> * doc/ref/data-rep.texi: Document unspecified?.
> ---
>  doc/ref/data-rep.texi | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi
> index bb7f74afe..f179a3560 100644
> --- a/doc/ref/data-rep.texi
> +++ b/doc/ref/data-rep.texi
> @@ -470,6 +470,9 @@ check to see if @var{x} is @code{SCM_UNBOUND}.  History will not be kind
>  to us.
>  @end deftypefn
>  
> +@deffn {Scheme Procedure} unspecified? x
> +Return @code{#t} if @var{x} is unspecified, else @code{#f}.
> +@end deffn

I'm not sure it's a good idea to document this procedure as part of our
public API, but if we were to document it, it would require a more
informative description.

It's nonsensical to ask whether a given object is "unspecified".  When
the Scheme standards say that the result of a computation is an
unspecified value, that means that *any* Scheme object could be
returned.

In Guile, for historical reasons, we usually return a particular object
SCM_UNSPECIFIED (a.k.a. *unspecified*) in cases where the specification
says that the result is unspecified.  However, we make no promises that
this will remain the case in future versions of Guile.

The number of legitimate uses for 'unspecified?' is extremely small.  In
fact, I can think of only one: when a REPL prints the result of a user's
computation, it is nice to avoid printing "*unspecified*" and instead
print nothing in that case.

In almost every other case, use of 'unspecified?' implies an assumption
that it's possible to detect when a value is an "unspecified" value,
when in fact that is fundamentally impossible.

What do you think?

      Mark