bug#18211: 24.4.50; doc string of `posnp'

bug#18211: 24.4.50; doc string of `posnp'

[Drew Adams]

Doc string:

 Return non-nil if OBJ appears to be a valid `posn' object.

What is a `posn' object?  What is a valid one?

(elisp) `Accessing Mouse' gives an understandable description.  If it is
correct then use something similar for the doc string:

     returns non-`nil' if OBJECT is a mouse position list,
                                    ^^^^^^^^^^^^^^^^^^^^^
     in either of the formats documented in *note Click
     Events::); and `nil' otherwise.

(FWIW, that manual text should not say "either", since there are more
than two such formats.  It should say "one".)



In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#18211: 24.4.50; doc string of `posnp'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Doc string:
>
>  Return non-nil if OBJ appears to be a valid `posn' object.
>
> What is a `posn' object?  What is a valid one?
>
> (elisp) `Accessing Mouse' gives an understandable description.  If it is
> correct then use something similar for the doc string:
>
>      returns non-`nil' if OBJECT is a mouse position list,
>                                     ^^^^^^^^^^^^^^^^^^^^^
>      in either of the formats documented in *note Click
>      Events::); and `nil' otherwise.
>
> (FWIW, that manual text should not say "either", since there are more
> than two such formats.  It should say "one".)

It currently says:

posnp is a compiled Lisp function in ‘subr.el’.

(posnp OBJ)

Return non-nil if OBJ appears to be a valid ‘posn’ object specifying a window.
If OBJ is a valid ‘posn’ object, but specifies a frame rather
than a window, return nil.

-----

I still don't know what it is, though.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#18211: 24.4.50; doc string of `posnp'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sat, 30 Apr 2016 02:41:23 +0200
> Cc: 18211@debbugs.gnu.org
> 
> posnp is a compiled Lisp function in ‘subr.el’.
> 
> (posnp OBJ)
> 
> Return non-nil if OBJ appears to be a valid ‘posn’ object specifying a window.
> If OBJ is a valid ‘posn’ object, but specifies a frame rather
> than a window, return nil.
> 
> -----
> 
> I still don't know what it is, though.  :-)

It's an object returned by event-start.

bug#18211: 24.4.50; doc string of `posnp'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> It's an object returned by event-start.

Thanks; I've now added this to the doc string.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no