bug#33168: 26; Doc string of `region-bounds'

bug#33168: 26; Doc string of `region-bounds'

[Drew Adams]

Doc string:

  Return the boundaries of the region as a pair of positions.
  Value is a list of cons cells of the form (START . END).

Those two sentences are incompatible.

The first says that it returns a _single pair_ of positions: (START END)
or (START . END).  (It doesn't say what it means by "pair".  If it means
a cons then it should say so.)

The second says that it returns a _list of such pairs_, that is, a list
of conses of the form (START . END), where START and END are buffer
positions.

Further, assuming that the second sentence is correct, something needs
to be said about what it means to be a boundary of the region.
Presumably, in the case of a contiguous region the return value is
((BEG . END)), where BEG is the start of the region and END is the END.
But what if the region is noncontiguous?  Something should be said
about what each (BEG<N> . END<N>) pair corresponds to (means).


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#33168: 26; Doc string of `region-bounds'

[Eli Zaretskii]

> Date: Fri, 26 Oct 2018 08:48:17 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Doc string:
> 
>   Return the boundaries of the region as a pair of positions.
>   Value is a list of cons cells of the form (START . END).
> 
> Those two sentences are incompatible.

Right; fixed.

> Further, assuming that the second sentence is correct, something needs
> to be said about what it means to be a boundary of the region.

I said "something" about that.

> Presumably, in the case of a contiguous region the return value is
> ((BEG . END)), where BEG is the start of the region and END is the END.
> But what if the region is noncontiguous?  Something should be said
> about what each (BEG<N> . END<N>) pair corresponds to (means).

And about this.

Thanks.