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."
XShapeQueryExtension.3x
XmbufQueryExtension.3x
Thanks,
-Ross
--- 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.
+structure. It returns a nonzero status on success; otherwise, it returns a
+zero status.
.LP
.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.
.SH STRUCTURES
The
.ZN XWindowAttributes
-- System Information:
Debian Release: 3.1
Architecture: amd64 (x86_64)
Kernel: Linux 2.6.14.5
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: