better docs

1 files changed, 39 insertions, 23 deletions

diff --git a/nexgb/xtest/xtest.go b/nexgb/xtest/xtest.go
index 357b325..e2a2d80 100644
--- a/nexgb/xtest/xtest.go
+++ b/nexgb/xtest/xtest.go
@@ -2,7 +2,7 @@
 package xtest
 
 /*
-	This file was generated by xtest.xml on May 10 2012 8:04:33pm EDT.
+	This file was generated by xtest.xml on May 10 2012 11:56:20pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -69,34 +69,36 @@ const (
 	CursorCurrent = 1
 )
 
-// Request GetVersion
-// size: 8
+// GetVersionCookie is a cookie used only for GetVersion requests.
 type GetVersionCookie struct {
 	*xgb.Cookie
 }
 
+// GetVersion sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetVersionCookie.Reply()
 func GetVersion(c *xgb.Conn, MajorVersion byte, MinorVersion uint16) GetVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getVersionRequest(c, MajorVersion, MinorVersion), cookie)
 	return GetVersionCookie{cookie}
 }
 
+// GetVersionUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetVersionUnchecked(c *xgb.Conn, MajorVersion byte, MinorVersion uint16) GetVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getVersionRequest(c, MajorVersion, MinorVersion), cookie)
 	return GetVersionCookie{cookie}
 }
 
-// Request reply for GetVersion
-// size: 10
+// GetVersionReply represents the data returned from a GetVersion request.
 type GetVersionReply struct {
-	Sequence     uint16
-	Length       uint32
+	Sequence     uint16 // sequence number of the request for this reply
+	Length       uint32 // number of bytes in this reply
 	MajorVersion byte
 	MinorVersion uint16
 }
 
-// Waits and reads reply data from request GetVersion
+// Reply blocks and returns the reply data for a GetVersion request.
 func (cook GetVersionCookie) Reply() (*GetVersionReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -108,7 +110,7 @@ func (cook GetVersionCookie) Reply() (*GetVersionReply, error) {
 	return getVersionReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetVersion
+// getVersionReply reads a byte slice into a GetVersionReply value.
 func getVersionReply(buf []byte) *GetVersionReply {
 	v := new(GetVersionReply)
 	b := 1 // skip reply determinant
@@ -129,6 +131,7 @@ func getVersionReply(buf []byte) *GetVersionReply {
 }
 
 // Write request to wire for GetVersion
+// getVersionRequest writes a GetVersion request to a byte slice.
 func getVersionRequest(c *xgb.Conn, MajorVersion byte, MinorVersion uint16) []byte {
 	size := 8
 	b := 0
@@ -154,33 +157,35 @@ func getVersionRequest(c *xgb.Conn, MajorVersion byte, MinorVersion uint16) []by
 	return buf
 }
 
-// Request CompareCursor
-// size: 12
+// CompareCursorCookie is a cookie used only for CompareCursor requests.
 type CompareCursorCookie struct {
 	*xgb.Cookie
 }
 
+// CompareCursor sends a checked request.
+// If an error occurs, it will be returned with the reply by calling CompareCursorCookie.Reply()
 func CompareCursor(c *xgb.Conn, Window xproto.Window, Cursor xproto.Cursor) CompareCursorCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(compareCursorRequest(c, Window, Cursor), cookie)
 	return CompareCursorCookie{cookie}
 }
 
+// CompareCursorUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CompareCursorUnchecked(c *xgb.Conn, Window xproto.Window, Cursor xproto.Cursor) CompareCursorCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(compareCursorRequest(c, Window, Cursor), cookie)
 	return CompareCursorCookie{cookie}
 }
 
-// Request reply for CompareCursor
-// size: 8
+// CompareCursorReply represents the data returned from a CompareCursor request.
 type CompareCursorReply struct {
-	Sequence uint16
-	Length   uint32
+	Sequence uint16 // sequence number of the request for this reply
+	Length   uint32 // number of bytes in this reply
 	Same     bool
 }
 
-// Waits and reads reply data from request CompareCursor
+// Reply blocks and returns the reply data for a CompareCursor request.
 func (cook CompareCursorCookie) Reply() (*CompareCursorReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -192,7 +197,7 @@ func (cook CompareCursorCookie) Reply() (*CompareCursorReply, error) {
 	return compareCursorReply(buf), nil
 }
 
-// Read reply into structure from buffer for CompareCursor
+// compareCursorReply reads a byte slice into a CompareCursorReply value.
 func compareCursorReply(buf []byte) *CompareCursorReply {
 	v := new(CompareCursorReply)
 	b := 1 // skip reply determinant
@@ -214,6 +219,7 @@ func compareCursorReply(buf []byte) *CompareCursorReply {
 }
 
 // Write request to wire for CompareCursor
+// compareCursorRequest writes a CompareCursor request to a byte slice.
 func compareCursorRequest(c *xgb.Conn, Window xproto.Window, Cursor xproto.Cursor) []byte {
 	size := 12
 	b := 0
@@ -237,30 +243,35 @@ func compareCursorRequest(c *xgb.Conn, Window xproto.Window, Cursor xproto.Curso
 	return buf
 }
 
-// Request FakeInput
-// size: 36
+// FakeInputCookie is a cookie used only for FakeInput requests.
 type FakeInputCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for FakeInput
+// FakeInput sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func FakeInput(c *xgb.Conn, Type byte, Detail byte, Time uint32, Root xproto.Window, RootX int16, RootY int16, Deviceid byte) FakeInputCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(fakeInputRequest(c, Type, Detail, Time, Root, RootX, RootY, Deviceid), cookie)
 	return FakeInputCookie{cookie}
 }
 
+// FakeInputChecked sends a checked request.
+// If an error occurs, it can be retrieved using FakeInputCookie.Check()
 func FakeInputChecked(c *xgb.Conn, Type byte, Detail byte, Time uint32, Root xproto.Window, RootX int16, RootY int16, Deviceid byte) FakeInputCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(fakeInputRequest(c, Type, Detail, Time, Root, RootX, RootY, Deviceid), cookie)
 	return FakeInputCookie{cookie}
 }
 
+// Check returns an error if one occurred for checked requests that are not expecting a reply.
+// This cannot be called for requests expecting a reply, nor for unchecked requests.
 func (cook FakeInputCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for FakeInput
+// fakeInputRequest writes a FakeInput request to a byte slice.
 func fakeInputRequest(c *xgb.Conn, Type byte, Detail byte, Time uint32, Root xproto.Window, RootX int16, RootY int16, Deviceid byte) []byte {
 	size := 36
 	b := 0
@@ -305,30 +316,35 @@ func fakeInputRequest(c *xgb.Conn, Type byte, Detail byte, Time uint32, Root xpr
 	return buf
 }
 
-// Request GrabControl
-// size: 8
+// GrabControlCookie is a cookie used only for GrabControl requests.
 type GrabControlCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for GrabControl
+// GrabControl sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GrabControl(c *xgb.Conn, Impervious bool) GrabControlCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(grabControlRequest(c, Impervious), cookie)
 	return GrabControlCookie{cookie}
 }
 
+// GrabControlChecked sends a checked request.
+// If an error occurs, it can be retrieved using GrabControlCookie.Check()
 func GrabControlChecked(c *xgb.Conn, Impervious bool) GrabControlCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(grabControlRequest(c, Impervious), cookie)
 	return GrabControlCookie{cookie}
 }
 
+// Check returns an error if one occurred for checked requests that are not expecting a reply.
+// This cannot be called for requests expecting a reply, nor for unchecked requests.
 func (cook GrabControlCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for GrabControl
+// grabControlRequest writes a GrabControl request to a byte slice.
 func grabControlRequest(c *xgb.Conn, Impervious bool) []byte {
 	size := 8
 	b := 0