[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#354315: libx11-dev: XGetWindowAttributes man page is misleading

Package: libx11-dev
Version: 4.3.0.dfsg.1-14sarge1
Severity: normal
Tags: patch

This man page does not discuss the actual return values of the
function, but says they are of type "Status".  One might assume
that this means you could compare it with the "Success" macro.
One would be wrong.

The X functions seem to have two three types representing status.
If it is an "int" there are a number of error codes or "Success"
which can be compared against.  If it is a bool, the result can be
compared with "True" or "False".  If the return type is "Status" it
appears that the return type is either 0 or 1.  Unfortunately the
value for Success is zero, so it is important to distinguish
between the first two types of return values and the third;
otherwise the conditional will be inverted.

XGetWindowAttributes() is one of the functions which returns zero
for failure.  The man page should make this clear.

A simple patch is provided below.

As a general note, the quality of the X11 API documentation is low.
Much of it seems to be boiler-plate and obvious questions and
caveats are not documented.  Of particular note, the meanings of
individual function parameters are often not explained (things like
"time   Specifies the time" -- time of what?).  And some pages
document functions which have little to do with each other.
Should I submit bug reports for those items as I notice them?

Also, two of the pages specifically state they are incomplete:

 "This manual pages[sic] needs a lot more work."



--- XGetWindowAttributes.3x     2006-02-24 20:47:24.000000000 -0600
+++ XGetWindowAttributes.3x-updated     2006-02-24 20:48:17.000000000 -0600
@@ -192,7 +192,8 @@
 .ZN XGetWindowAttributes
 function returns the current attributes for the specified window to an
 .ZN XWindowAttributes
+structure.  It returns a nonzero status on success; otherwise, it returns a
+zero status.
 .ZN XGetWindowAttributes
 can generate
@@ -209,6 +210,8 @@
 These are described in the argument list.
 It is legal to pass to this function a window whose class is
 .ZN InputOnly .
+It returns a nonzero status on success; otherwise, it returns a
+zero status.
 .ZN XWindowAttributes

-- System Information:
Debian Release: 3.1
Architecture: amd64 (x86_64)
Kernel: Linux
Locale: LANG=en_US, LC_CTYPE=en_US (charmap=ANSI_X3.4-1968) (ignored: LC_ALL set to C)

Versions of packages libx11-dev depends on:
ii  libc6-dev [libc-de 2.3.2.ds1-22          GNU C Library: Development Librari
ii  libx11-6           4.3.0.dfsg.1-14sarge1 X Window System protocol client li
ii  libxext-dev        4.3.0.dfsg.1-14sarge1 X Window System miscellaneous exte
ii  libxi-dev          4.3.0.dfsg.1-14sarge1 X Window System Input extension li
ii  x-dev              4.3.0.dfsg.1-14sarge1 X protocol development files
ii  xfree86-common     4.3.0.dfsg.1-14sarge1 X Window System (XFree86) infrastr
ii  xlibs-static-dev   4.3.0.dfsg.1-14sarge1 X Window System client library dev

-- no debconf information

Reply to: