better docs

1 files changed, 89 insertions, 48 deletions

diff --git a/nexgb/composite/composite.go b/nexgb/composite/composite.go
index 5a3d7c4..be56807 100644
--- a/nexgb/composite/composite.go
+++ b/nexgb/composite/composite.go
@@ -2,7 +2,7 @@
 package composite
 
 /*
-	This file was generated by composite.xml on May 10 2012 8:04:31pm EDT.
+	This file was generated by composite.xml on May 10 2012 11:56:18pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -41,16 +41,6 @@ func init() {
 	xgb.NewExtErrorFuncs["Composite"] = make(map[int]xgb.NewErrorFun)
 }
 
-// Skipping definition for base type 'Card8'
-
-// Skipping definition for base type 'Int16'
-
-// Skipping definition for base type 'Int32'
-
-// Skipping definition for base type 'Void'
-
-// Skipping definition for base type 'Byte'
-
 // Skipping definition for base type 'Int8'
 
 // Skipping definition for base type 'Card16'
@@ -65,41 +55,53 @@ func init() {
 
 // Skipping definition for base type 'Float'
 
+// Skipping definition for base type 'Card8'
+
+// Skipping definition for base type 'Int16'
+
+// Skipping definition for base type 'Int32'
+
+// Skipping definition for base type 'Void'
+
+// Skipping definition for base type 'Byte'
+
 const (
 	RedirectAutomatic = 0
 	RedirectManual    = 1
 )
 
-// Request QueryVersion
-// size: 12
+// QueryVersionCookie is a cookie used only for QueryVersion requests.
 type QueryVersionCookie struct {
 	*xgb.Cookie
 }
 
+// QueryVersion sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryVersionCookie.Reply()
 func QueryVersion(c *xgb.Conn, ClientMajorVersion uint32, ClientMinorVersion uint32) QueryVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryVersionRequest(c, ClientMajorVersion, ClientMinorVersion), cookie)
 	return QueryVersionCookie{cookie}
 }
 
+// QueryVersionUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryVersionUnchecked(c *xgb.Conn, ClientMajorVersion uint32, ClientMinorVersion uint32) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c, ClientMajorVersion, ClientMinorVersion), cookie)
 	return QueryVersionCookie{cookie}
 }
 
-// Request reply for QueryVersion
-// size: 32
+// QueryVersionReply represents the data returned from a QueryVersion request.
 type QueryVersionReply struct {
-	Sequence uint16
-	Length   uint32
+	Sequence uint16 // sequence number of the request for this reply
+	Length   uint32 // number of bytes in this reply
 	// padding: 1 bytes
 	MajorVersion uint32
 	MinorVersion uint32
 	// padding: 16 bytes
 }
 
-// Waits and reads reply data from request QueryVersion
+// Reply blocks and returns the reply data for a QueryVersion request.
 func (cook QueryVersionCookie) Reply() (*QueryVersionReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -111,7 +113,7 @@ func (cook QueryVersionCookie) Reply() (*QueryVersionReply, error) {
 	return queryVersionReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryVersion
+// queryVersionReply reads a byte slice into a QueryVersionReply value.
 func queryVersionReply(buf []byte) *QueryVersionReply {
 	v := new(QueryVersionReply)
 	b := 1 // skip reply determinant
@@ -136,6 +138,7 @@ func queryVersionReply(buf []byte) *QueryVersionReply {
 }
 
 // Write request to wire for QueryVersion
+// queryVersionRequest writes a QueryVersion request to a byte slice.
 func queryVersionRequest(c *xgb.Conn, ClientMajorVersion uint32, ClientMinorVersion uint32) []byte {
 	size := 12
 	b := 0
@@ -159,30 +162,35 @@ func queryVersionRequest(c *xgb.Conn, ClientMajorVersion uint32, ClientMinorVers
 	return buf
 }
 
-// Request RedirectWindow
-// size: 12
+// RedirectWindowCookie is a cookie used only for RedirectWindow requests.
 type RedirectWindowCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for RedirectWindow
+// RedirectWindow sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func RedirectWindow(c *xgb.Conn, Window xproto.Window, Update byte) RedirectWindowCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(redirectWindowRequest(c, Window, Update), cookie)
 	return RedirectWindowCookie{cookie}
 }
 
+// RedirectWindowChecked sends a checked request.
+// If an error occurs, it can be retrieved using RedirectWindowCookie.Check()
 func RedirectWindowChecked(c *xgb.Conn, Window xproto.Window, Update byte) RedirectWindowCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(redirectWindowRequest(c, Window, Update), cookie)
 	return RedirectWindowCookie{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 RedirectWindowCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for RedirectWindow
+// redirectWindowRequest writes a RedirectWindow request to a byte slice.
 func redirectWindowRequest(c *xgb.Conn, Window xproto.Window, Update byte) []byte {
 	size := 12
 	b := 0
@@ -208,30 +216,35 @@ func redirectWindowRequest(c *xgb.Conn, Window xproto.Window, Update byte) []byt
 	return buf
 }
 
-// Request RedirectSubwindows
-// size: 12
+// RedirectSubwindowsCookie is a cookie used only for RedirectSubwindows requests.
 type RedirectSubwindowsCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for RedirectSubwindows
+// RedirectSubwindows sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func RedirectSubwindows(c *xgb.Conn, Window xproto.Window, Update byte) RedirectSubwindowsCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(redirectSubwindowsRequest(c, Window, Update), cookie)
 	return RedirectSubwindowsCookie{cookie}
 }
 
+// RedirectSubwindowsChecked sends a checked request.
+// If an error occurs, it can be retrieved using RedirectSubwindowsCookie.Check()
 func RedirectSubwindowsChecked(c *xgb.Conn, Window xproto.Window, Update byte) RedirectSubwindowsCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(redirectSubwindowsRequest(c, Window, Update), cookie)
 	return RedirectSubwindowsCookie{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 RedirectSubwindowsCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for RedirectSubwindows
+// redirectSubwindowsRequest writes a RedirectSubwindows request to a byte slice.
 func redirectSubwindowsRequest(c *xgb.Conn, Window xproto.Window, Update byte) []byte {
 	size := 12
 	b := 0
@@ -257,30 +270,35 @@ func redirectSubwindowsRequest(c *xgb.Conn, Window xproto.Window, Update byte) [
 	return buf
 }
 
-// Request UnredirectWindow
-// size: 12
+// UnredirectWindowCookie is a cookie used only for UnredirectWindow requests.
 type UnredirectWindowCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for UnredirectWindow
+// UnredirectWindow sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func UnredirectWindow(c *xgb.Conn, Window xproto.Window, Update byte) UnredirectWindowCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(unredirectWindowRequest(c, Window, Update), cookie)
 	return UnredirectWindowCookie{cookie}
 }
 
+// UnredirectWindowChecked sends a checked request.
+// If an error occurs, it can be retrieved using UnredirectWindowCookie.Check()
 func UnredirectWindowChecked(c *xgb.Conn, Window xproto.Window, Update byte) UnredirectWindowCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(unredirectWindowRequest(c, Window, Update), cookie)
 	return UnredirectWindowCookie{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 UnredirectWindowCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for UnredirectWindow
+// unredirectWindowRequest writes a UnredirectWindow request to a byte slice.
 func unredirectWindowRequest(c *xgb.Conn, Window xproto.Window, Update byte) []byte {
 	size := 12
 	b := 0
@@ -306,30 +324,35 @@ func unredirectWindowRequest(c *xgb.Conn, Window xproto.Window, Update byte) []b
 	return buf
 }
 
-// Request UnredirectSubwindows
-// size: 12
+// UnredirectSubwindowsCookie is a cookie used only for UnredirectSubwindows requests.
 type UnredirectSubwindowsCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for UnredirectSubwindows
+// UnredirectSubwindows sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func UnredirectSubwindows(c *xgb.Conn, Window xproto.Window, Update byte) UnredirectSubwindowsCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(unredirectSubwindowsRequest(c, Window, Update), cookie)
 	return UnredirectSubwindowsCookie{cookie}
 }
 
+// UnredirectSubwindowsChecked sends a checked request.
+// If an error occurs, it can be retrieved using UnredirectSubwindowsCookie.Check()
 func UnredirectSubwindowsChecked(c *xgb.Conn, Window xproto.Window, Update byte) UnredirectSubwindowsCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(unredirectSubwindowsRequest(c, Window, Update), cookie)
 	return UnredirectSubwindowsCookie{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 UnredirectSubwindowsCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for UnredirectSubwindows
+// unredirectSubwindowsRequest writes a UnredirectSubwindows request to a byte slice.
 func unredirectSubwindowsRequest(c *xgb.Conn, Window xproto.Window, Update byte) []byte {
 	size := 12
 	b := 0
@@ -355,30 +378,35 @@ func unredirectSubwindowsRequest(c *xgb.Conn, Window xproto.Window, Update byte)
 	return buf
 }
 
-// Request CreateRegionFromBorderClip
-// size: 12
+// CreateRegionFromBorderClipCookie is a cookie used only for CreateRegionFromBorderClip requests.
 type CreateRegionFromBorderClipCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for CreateRegionFromBorderClip
+// CreateRegionFromBorderClip sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CreateRegionFromBorderClip(c *xgb.Conn, Region xfixes.Region, Window xproto.Window) CreateRegionFromBorderClipCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(createRegionFromBorderClipRequest(c, Region, Window), cookie)
 	return CreateRegionFromBorderClipCookie{cookie}
 }
 
+// CreateRegionFromBorderClipChecked sends a checked request.
+// If an error occurs, it can be retrieved using CreateRegionFromBorderClipCookie.Check()
 func CreateRegionFromBorderClipChecked(c *xgb.Conn, Region xfixes.Region, Window xproto.Window) CreateRegionFromBorderClipCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(createRegionFromBorderClipRequest(c, Region, Window), cookie)
 	return CreateRegionFromBorderClipCookie{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 CreateRegionFromBorderClipCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for CreateRegionFromBorderClip
+// createRegionFromBorderClipRequest writes a CreateRegionFromBorderClip request to a byte slice.
 func createRegionFromBorderClipRequest(c *xgb.Conn, Region xfixes.Region, Window xproto.Window) []byte {
 	size := 12
 	b := 0
@@ -402,30 +430,35 @@ func createRegionFromBorderClipRequest(c *xgb.Conn, Region xfixes.Region, Window
 	return buf
 }
 
-// Request NameWindowPixmap
-// size: 12
+// NameWindowPixmapCookie is a cookie used only for NameWindowPixmap requests.
 type NameWindowPixmapCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for NameWindowPixmap
+// NameWindowPixmap sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func NameWindowPixmap(c *xgb.Conn, Window xproto.Window, Pixmap xproto.Pixmap) NameWindowPixmapCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(nameWindowPixmapRequest(c, Window, Pixmap), cookie)
 	return NameWindowPixmapCookie{cookie}
 }
 
+// NameWindowPixmapChecked sends a checked request.
+// If an error occurs, it can be retrieved using NameWindowPixmapCookie.Check()
 func NameWindowPixmapChecked(c *xgb.Conn, Window xproto.Window, Pixmap xproto.Pixmap) NameWindowPixmapCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(nameWindowPixmapRequest(c, Window, Pixmap), cookie)
 	return NameWindowPixmapCookie{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 NameWindowPixmapCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for NameWindowPixmap
+// nameWindowPixmapRequest writes a NameWindowPixmap request to a byte slice.
 func nameWindowPixmapRequest(c *xgb.Conn, Window xproto.Window, Pixmap xproto.Pixmap) []byte {
 	size := 12
 	b := 0
@@ -449,35 +482,37 @@ func nameWindowPixmapRequest(c *xgb.Conn, Window xproto.Window, Pixmap xproto.Pi
 	return buf
 }
 
-// Request GetOverlayWindow
-// size: 8
+// GetOverlayWindowCookie is a cookie used only for GetOverlayWindow requests.
 type GetOverlayWindowCookie struct {
 	*xgb.Cookie
 }
 
+// GetOverlayWindow sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetOverlayWindowCookie.Reply()
 func GetOverlayWindow(c *xgb.Conn, Window xproto.Window) GetOverlayWindowCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getOverlayWindowRequest(c, Window), cookie)
 	return GetOverlayWindowCookie{cookie}
 }
 
+// GetOverlayWindowUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetOverlayWindowUnchecked(c *xgb.Conn, Window xproto.Window) GetOverlayWindowCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getOverlayWindowRequest(c, Window), cookie)
 	return GetOverlayWindowCookie{cookie}
 }
 
-// Request reply for GetOverlayWindow
-// size: 32
+// GetOverlayWindowReply represents the data returned from a GetOverlayWindow request.
 type GetOverlayWindowReply struct {
-	Sequence uint16
-	Length   uint32
+	Sequence uint16 // sequence number of the request for this reply
+	Length   uint32 // number of bytes in this reply
 	// padding: 1 bytes
 	OverlayWin xproto.Window
 	// padding: 20 bytes
 }
 
-// Waits and reads reply data from request GetOverlayWindow
+// Reply blocks and returns the reply data for a GetOverlayWindow request.
 func (cook GetOverlayWindowCookie) Reply() (*GetOverlayWindowReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -489,7 +524,7 @@ func (cook GetOverlayWindowCookie) Reply() (*GetOverlayWindowReply, error) {
 	return getOverlayWindowReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetOverlayWindow
+// getOverlayWindowReply reads a byte slice into a GetOverlayWindowReply value.
 func getOverlayWindowReply(buf []byte) *GetOverlayWindowReply {
 	v := new(GetOverlayWindowReply)
 	b := 1 // skip reply determinant
@@ -511,6 +546,7 @@ func getOverlayWindowReply(buf []byte) *GetOverlayWindowReply {
 }
 
 // Write request to wire for GetOverlayWindow
+// getOverlayWindowRequest writes a GetOverlayWindow request to a byte slice.
 func getOverlayWindowRequest(c *xgb.Conn, Window xproto.Window) []byte {
 	size := 8
 	b := 0
@@ -531,30 +567,35 @@ func getOverlayWindowRequest(c *xgb.Conn, Window xproto.Window) []byte {
 	return buf
 }
 
-// Request ReleaseOverlayWindow
-// size: 8
+// ReleaseOverlayWindowCookie is a cookie used only for ReleaseOverlayWindow requests.
 type ReleaseOverlayWindowCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for ReleaseOverlayWindow
+// ReleaseOverlayWindow sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func ReleaseOverlayWindow(c *xgb.Conn, Window xproto.Window) ReleaseOverlayWindowCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(releaseOverlayWindowRequest(c, Window), cookie)
 	return ReleaseOverlayWindowCookie{cookie}
 }
 
+// ReleaseOverlayWindowChecked sends a checked request.
+// If an error occurs, it can be retrieved using ReleaseOverlayWindowCookie.Check()
 func ReleaseOverlayWindowChecked(c *xgb.Conn, Window xproto.Window) ReleaseOverlayWindowCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(releaseOverlayWindowRequest(c, Window), cookie)
 	return ReleaseOverlayWindowCookie{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 ReleaseOverlayWindowCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for ReleaseOverlayWindow
+// releaseOverlayWindowRequest writes a ReleaseOverlayWindow request to a byte slice.
 func releaseOverlayWindowRequest(c *xgb.Conn, Window xproto.Window) []byte {
 	size := 8
 	b := 0