better docs

1 files changed, 140 insertions, 100 deletions

diff --git a/nexgb/xf86dri/xf86dri.go b/nexgb/xf86dri/xf86dri.go
index ac87c0a..cd3ff35 100644
--- a/nexgb/xf86dri/xf86dri.go
+++ b/nexgb/xf86dri/xf86dri.go
@@ -2,7 +2,7 @@
 package xf86dri
 
 /*
-	This file was generated by xf86dri.xml on May 10 2012 8:04:32pm EDT.
+	This file was generated by xf86dri.xml on May 10 2012 11:56:19pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -40,18 +40,6 @@ func init() {
 	xgb.NewExtErrorFuncs["XFree86-DRI"] = make(map[int]xgb.NewErrorFun)
 }
 
-// Skipping definition for base type 'Int8'
-
-// Skipping definition for base type 'Card16'
-
-// Skipping definition for base type 'Char'
-
-// Skipping definition for base type 'Card32'
-
-// Skipping definition for base type 'Double'
-
-// Skipping definition for base type 'Bool'
-
 // Skipping definition for base type 'Float'
 
 // Skipping definition for base type 'Card8'
@@ -64,8 +52,18 @@ func init() {
 
 // Skipping definition for base type 'Byte'
 
-// 'DrmClipRect' struct definition
-// Size: 8
+// Skipping definition for base type 'Int8'
+
+// Skipping definition for base type 'Card16'
+
+// Skipping definition for base type 'Char'
+
+// Skipping definition for base type 'Card32'
+
+// Skipping definition for base type 'Double'
+
+// Skipping definition for base type 'Bool'
+
 type DrmClipRect struct {
 	X1 int16
 	Y1 int16
@@ -73,7 +71,7 @@ type DrmClipRect struct {
 	X3 int16
 }
 
-// Struct read DrmClipRect
+// DrmClipRectRead reads a byte slice into a DrmClipRect value.
 func DrmClipRectRead(buf []byte, v *DrmClipRect) int {
 	b := 0
 
@@ -92,7 +90,7 @@ func DrmClipRectRead(buf []byte, v *DrmClipRect) int {
 	return b
 }
 
-// Struct list read DrmClipRect
+// DrmClipRectReadList reads a byte slice into a list of DrmClipRect values.
 func DrmClipRectReadList(buf []byte, dest []DrmClipRect) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -102,7 +100,7 @@ func DrmClipRectReadList(buf []byte, dest []DrmClipRect) int {
 	return xgb.Pad(b)
 }
 
-// Struct write DrmClipRect
+// Bytes writes a DrmClipRect value to a byte slice.
 func (v DrmClipRect) Bytes() []byte {
 	buf := make([]byte, 8)
 	b := 0
@@ -122,7 +120,7 @@ func (v DrmClipRect) Bytes() []byte {
 	return buf
 }
 
-// Write struct list DrmClipRect
+// DrmClipRectListBytes writes a list of %s(MISSING) values to a byte slice.
 func DrmClipRectListBytes(buf []byte, list []DrmClipRect) int {
 	b := 0
 	var structBytes []byte
@@ -134,36 +132,38 @@ func DrmClipRectListBytes(buf []byte, list []DrmClipRect) int {
 	return b
 }
 
-// Request QueryVersion
-// size: 4
+// 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) QueryVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryVersionRequest(c), 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) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c), cookie)
 	return QueryVersionCookie{cookie}
 }
 
-// Request reply for QueryVersion
-// size: 16
+// 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
 	DriMajorVersion uint16
 	DriMinorVersion uint16
 	DriMinorPatch   uint32
 }
 
-// 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 {
@@ -175,7 +175,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
@@ -201,6 +201,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) []byte {
 	size := 4
 	b := 0
@@ -218,34 +219,36 @@ func queryVersionRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request QueryDirectRenderingCapable
-// size: 8
+// QueryDirectRenderingCapableCookie is a cookie used only for QueryDirectRenderingCapable requests.
 type QueryDirectRenderingCapableCookie struct {
 	*xgb.Cookie
 }
 
+// QueryDirectRenderingCapable sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryDirectRenderingCapableCookie.Reply()
 func QueryDirectRenderingCapable(c *xgb.Conn, Screen uint32) QueryDirectRenderingCapableCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryDirectRenderingCapableRequest(c, Screen), cookie)
 	return QueryDirectRenderingCapableCookie{cookie}
 }
 
+// QueryDirectRenderingCapableUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryDirectRenderingCapableUnchecked(c *xgb.Conn, Screen uint32) QueryDirectRenderingCapableCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryDirectRenderingCapableRequest(c, Screen), cookie)
 	return QueryDirectRenderingCapableCookie{cookie}
 }
 
-// Request reply for QueryDirectRenderingCapable
-// size: 9
+// QueryDirectRenderingCapableReply represents the data returned from a QueryDirectRenderingCapable request.
 type QueryDirectRenderingCapableReply 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
 	IsCapable bool
 }
 
-// Waits and reads reply data from request QueryDirectRenderingCapable
+// Reply blocks and returns the reply data for a QueryDirectRenderingCapable request.
 func (cook QueryDirectRenderingCapableCookie) Reply() (*QueryDirectRenderingCapableReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -257,7 +260,7 @@ func (cook QueryDirectRenderingCapableCookie) Reply() (*QueryDirectRenderingCapa
 	return queryDirectRenderingCapableReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryDirectRenderingCapable
+// queryDirectRenderingCapableReply reads a byte slice into a QueryDirectRenderingCapableReply value.
 func queryDirectRenderingCapableReply(buf []byte) *QueryDirectRenderingCapableReply {
 	v := new(QueryDirectRenderingCapableReply)
 	b := 1 // skip reply determinant
@@ -281,6 +284,7 @@ func queryDirectRenderingCapableReply(buf []byte) *QueryDirectRenderingCapableRe
 }
 
 // Write request to wire for QueryDirectRenderingCapable
+// queryDirectRenderingCapableRequest writes a QueryDirectRenderingCapable request to a byte slice.
 func queryDirectRenderingCapableRequest(c *xgb.Conn, Screen uint32) []byte {
 	size := 8
 	b := 0
@@ -301,29 +305,31 @@ func queryDirectRenderingCapableRequest(c *xgb.Conn, Screen uint32) []byte {
 	return buf
 }
 
-// Request OpenConnection
-// size: 8
+// OpenConnectionCookie is a cookie used only for OpenConnection requests.
 type OpenConnectionCookie struct {
 	*xgb.Cookie
 }
 
+// OpenConnection sends a checked request.
+// If an error occurs, it will be returned with the reply by calling OpenConnectionCookie.Reply()
 func OpenConnection(c *xgb.Conn, Screen uint32) OpenConnectionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(openConnectionRequest(c, Screen), cookie)
 	return OpenConnectionCookie{cookie}
 }
 
+// OpenConnectionUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func OpenConnectionUnchecked(c *xgb.Conn, Screen uint32) OpenConnectionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(openConnectionRequest(c, Screen), cookie)
 	return OpenConnectionCookie{cookie}
 }
 
-// Request reply for OpenConnection
-// size: (32 + xgb.Pad((int(BusIdLen) * 1)))
+// OpenConnectionReply represents the data returned from a OpenConnection request.
 type OpenConnectionReply 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
 	SareaHandleLow  uint32
 	SareaHandleHigh uint32
@@ -332,7 +338,7 @@ type OpenConnectionReply struct {
 	BusId string // size: xgb.Pad((int(BusIdLen) * 1))
 }
 
-// Waits and reads reply data from request OpenConnection
+// Reply blocks and returns the reply data for a OpenConnection request.
 func (cook OpenConnectionCookie) Reply() (*OpenConnectionReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -344,7 +350,7 @@ func (cook OpenConnectionCookie) Reply() (*OpenConnectionReply, error) {
 	return openConnectionReply(buf), nil
 }
 
-// Read reply into structure from buffer for OpenConnection
+// openConnectionReply reads a byte slice into a OpenConnectionReply value.
 func openConnectionReply(buf []byte) *OpenConnectionReply {
 	v := new(OpenConnectionReply)
 	b := 1 // skip reply determinant
@@ -379,6 +385,7 @@ func openConnectionReply(buf []byte) *OpenConnectionReply {
 }
 
 // Write request to wire for OpenConnection
+// openConnectionRequest writes a OpenConnection request to a byte slice.
 func openConnectionRequest(c *xgb.Conn, Screen uint32) []byte {
 	size := 8
 	b := 0
@@ -399,30 +406,35 @@ func openConnectionRequest(c *xgb.Conn, Screen uint32) []byte {
 	return buf
 }
 
-// Request CloseConnection
-// size: 8
+// CloseConnectionCookie is a cookie used only for CloseConnection requests.
 type CloseConnectionCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for CloseConnection
+// CloseConnection sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CloseConnection(c *xgb.Conn, Screen uint32) CloseConnectionCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(closeConnectionRequest(c, Screen), cookie)
 	return CloseConnectionCookie{cookie}
 }
 
+// CloseConnectionChecked sends a checked request.
+// If an error occurs, it can be retrieved using CloseConnectionCookie.Check()
 func CloseConnectionChecked(c *xgb.Conn, Screen uint32) CloseConnectionCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(closeConnectionRequest(c, Screen), cookie)
 	return CloseConnectionCookie{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 CloseConnectionCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for CloseConnection
+// closeConnectionRequest writes a CloseConnection request to a byte slice.
 func closeConnectionRequest(c *xgb.Conn, Screen uint32) []byte {
 	size := 8
 	b := 0
@@ -443,29 +455,31 @@ func closeConnectionRequest(c *xgb.Conn, Screen uint32) []byte {
 	return buf
 }
 
-// Request GetClientDriverName
-// size: 8
+// GetClientDriverNameCookie is a cookie used only for GetClientDriverName requests.
 type GetClientDriverNameCookie struct {
 	*xgb.Cookie
 }
 
+// GetClientDriverName sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetClientDriverNameCookie.Reply()
 func GetClientDriverName(c *xgb.Conn, Screen uint32) GetClientDriverNameCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getClientDriverNameRequest(c, Screen), cookie)
 	return GetClientDriverNameCookie{cookie}
 }
 
+// GetClientDriverNameUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetClientDriverNameUnchecked(c *xgb.Conn, Screen uint32) GetClientDriverNameCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getClientDriverNameRequest(c, Screen), cookie)
 	return GetClientDriverNameCookie{cookie}
 }
 
-// Request reply for GetClientDriverName
-// size: (32 + xgb.Pad((int(ClientDriverNameLen) * 1)))
+// GetClientDriverNameReply represents the data returned from a GetClientDriverName request.
 type GetClientDriverNameReply 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
 	ClientDriverMajorVersion uint32
 	ClientDriverMinorVersion uint32
@@ -475,7 +489,7 @@ type GetClientDriverNameReply struct {
 	ClientDriverName string // size: xgb.Pad((int(ClientDriverNameLen) * 1))
 }
 
-// Waits and reads reply data from request GetClientDriverName
+// Reply blocks and returns the reply data for a GetClientDriverName request.
 func (cook GetClientDriverNameCookie) Reply() (*GetClientDriverNameReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -487,7 +501,7 @@ func (cook GetClientDriverNameCookie) Reply() (*GetClientDriverNameReply, error)
 	return getClientDriverNameReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetClientDriverName
+// getClientDriverNameReply reads a byte slice into a GetClientDriverNameReply value.
 func getClientDriverNameReply(buf []byte) *GetClientDriverNameReply {
 	v := new(GetClientDriverNameReply)
 	b := 1 // skip reply determinant
@@ -525,6 +539,7 @@ func getClientDriverNameReply(buf []byte) *GetClientDriverNameReply {
 }
 
 // Write request to wire for GetClientDriverName
+// getClientDriverNameRequest writes a GetClientDriverName request to a byte slice.
 func getClientDriverNameRequest(c *xgb.Conn, Screen uint32) []byte {
 	size := 8
 	b := 0
@@ -545,34 +560,36 @@ func getClientDriverNameRequest(c *xgb.Conn, Screen uint32) []byte {
 	return buf
 }
 
-// Request CreateContext
-// size: 16
+// CreateContextCookie is a cookie used only for CreateContext requests.
 type CreateContextCookie struct {
 	*xgb.Cookie
 }
 
+// CreateContext sends a checked request.
+// If an error occurs, it will be returned with the reply by calling CreateContextCookie.Reply()
 func CreateContext(c *xgb.Conn, Screen uint32, Visual uint32, Context uint32) CreateContextCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(createContextRequest(c, Screen, Visual, Context), cookie)
 	return CreateContextCookie{cookie}
 }
 
+// CreateContextUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CreateContextUnchecked(c *xgb.Conn, Screen uint32, Visual uint32, Context uint32) CreateContextCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(createContextRequest(c, Screen, Visual, Context), cookie)
 	return CreateContextCookie{cookie}
 }
 
-// Request reply for CreateContext
-// size: 12
+// CreateContextReply represents the data returned from a CreateContext request.
 type CreateContextReply 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
 	HwContext uint32
 }
 
-// Waits and reads reply data from request CreateContext
+// Reply blocks and returns the reply data for a CreateContext request.
 func (cook CreateContextCookie) Reply() (*CreateContextReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -584,7 +601,7 @@ func (cook CreateContextCookie) Reply() (*CreateContextReply, error) {
 	return createContextReply(buf), nil
 }
 
-// Read reply into structure from buffer for CreateContext
+// createContextReply reads a byte slice into a CreateContextReply value.
 func createContextReply(buf []byte) *CreateContextReply {
 	v := new(CreateContextReply)
 	b := 1 // skip reply determinant
@@ -604,6 +621,7 @@ func createContextReply(buf []byte) *CreateContextReply {
 }
 
 // Write request to wire for CreateContext
+// createContextRequest writes a CreateContext request to a byte slice.
 func createContextRequest(c *xgb.Conn, Screen uint32, Visual uint32, Context uint32) []byte {
 	size := 16
 	b := 0
@@ -630,30 +648,35 @@ func createContextRequest(c *xgb.Conn, Screen uint32, Visual uint32, Context uin
 	return buf
 }
 
-// Request DestroyContext
-// size: 12
+// DestroyContextCookie is a cookie used only for DestroyContext requests.
 type DestroyContextCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for DestroyContext
+// DestroyContext sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func DestroyContext(c *xgb.Conn, Screen uint32, Context uint32) DestroyContextCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(destroyContextRequest(c, Screen, Context), cookie)
 	return DestroyContextCookie{cookie}
 }
 
+// DestroyContextChecked sends a checked request.
+// If an error occurs, it can be retrieved using DestroyContextCookie.Check()
 func DestroyContextChecked(c *xgb.Conn, Screen uint32, Context uint32) DestroyContextCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(destroyContextRequest(c, Screen, Context), cookie)
 	return DestroyContextCookie{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 DestroyContextCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for DestroyContext
+// destroyContextRequest writes a DestroyContext request to a byte slice.
 func destroyContextRequest(c *xgb.Conn, Screen uint32, Context uint32) []byte {
 	size := 12
 	b := 0
@@ -677,34 +700,36 @@ func destroyContextRequest(c *xgb.Conn, Screen uint32, Context uint32) []byte {
 	return buf
 }
 
-// Request CreateDrawable
-// size: 12
+// CreateDrawableCookie is a cookie used only for CreateDrawable requests.
 type CreateDrawableCookie struct {
 	*xgb.Cookie
 }
 
+// CreateDrawable sends a checked request.
+// If an error occurs, it will be returned with the reply by calling CreateDrawableCookie.Reply()
 func CreateDrawable(c *xgb.Conn, Screen uint32, Drawable uint32) CreateDrawableCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(createDrawableRequest(c, Screen, Drawable), cookie)
 	return CreateDrawableCookie{cookie}
 }
 
+// CreateDrawableUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CreateDrawableUnchecked(c *xgb.Conn, Screen uint32, Drawable uint32) CreateDrawableCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(createDrawableRequest(c, Screen, Drawable), cookie)
 	return CreateDrawableCookie{cookie}
 }
 
-// Request reply for CreateDrawable
-// size: 12
+// CreateDrawableReply represents the data returned from a CreateDrawable request.
 type CreateDrawableReply 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
 	HwDrawableHandle uint32
 }
 
-// Waits and reads reply data from request CreateDrawable
+// Reply blocks and returns the reply data for a CreateDrawable request.
 func (cook CreateDrawableCookie) Reply() (*CreateDrawableReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -716,7 +741,7 @@ func (cook CreateDrawableCookie) Reply() (*CreateDrawableReply, error) {
 	return createDrawableReply(buf), nil
 }
 
-// Read reply into structure from buffer for CreateDrawable
+// createDrawableReply reads a byte slice into a CreateDrawableReply value.
 func createDrawableReply(buf []byte) *CreateDrawableReply {
 	v := new(CreateDrawableReply)
 	b := 1 // skip reply determinant
@@ -736,6 +761,7 @@ func createDrawableReply(buf []byte) *CreateDrawableReply {
 }
 
 // Write request to wire for CreateDrawable
+// createDrawableRequest writes a CreateDrawable request to a byte slice.
 func createDrawableRequest(c *xgb.Conn, Screen uint32, Drawable uint32) []byte {
 	size := 12
 	b := 0
@@ -759,30 +785,35 @@ func createDrawableRequest(c *xgb.Conn, Screen uint32, Drawable uint32) []byte {
 	return buf
 }
 
-// Request DestroyDrawable
-// size: 12
+// DestroyDrawableCookie is a cookie used only for DestroyDrawable requests.
 type DestroyDrawableCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for DestroyDrawable
+// DestroyDrawable sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func DestroyDrawable(c *xgb.Conn, Screen uint32, Drawable uint32) DestroyDrawableCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(destroyDrawableRequest(c, Screen, Drawable), cookie)
 	return DestroyDrawableCookie{cookie}
 }
 
+// DestroyDrawableChecked sends a checked request.
+// If an error occurs, it can be retrieved using DestroyDrawableCookie.Check()
 func DestroyDrawableChecked(c *xgb.Conn, Screen uint32, Drawable uint32) DestroyDrawableCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(destroyDrawableRequest(c, Screen, Drawable), cookie)
 	return DestroyDrawableCookie{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 DestroyDrawableCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for DestroyDrawable
+// destroyDrawableRequest writes a DestroyDrawable request to a byte slice.
 func destroyDrawableRequest(c *xgb.Conn, Screen uint32, Drawable uint32) []byte {
 	size := 12
 	b := 0
@@ -806,29 +837,31 @@ func destroyDrawableRequest(c *xgb.Conn, Screen uint32, Drawable uint32) []byte
 	return buf
 }
 
-// Request GetDrawableInfo
-// size: 12
+// GetDrawableInfoCookie is a cookie used only for GetDrawableInfo requests.
 type GetDrawableInfoCookie struct {
 	*xgb.Cookie
 }
 
+// GetDrawableInfo sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetDrawableInfoCookie.Reply()
 func GetDrawableInfo(c *xgb.Conn, Screen uint32, Drawable uint32) GetDrawableInfoCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getDrawableInfoRequest(c, Screen, Drawable), cookie)
 	return GetDrawableInfoCookie{cookie}
 }
 
+// GetDrawableInfoUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetDrawableInfoUnchecked(c *xgb.Conn, Screen uint32, Drawable uint32) GetDrawableInfoCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getDrawableInfoRequest(c, Screen, Drawable), cookie)
 	return GetDrawableInfoCookie{cookie}
 }
 
-// Request reply for GetDrawableInfo
-// size: ((36 + xgb.Pad((int(NumClipRects) * 8))) + xgb.Pad((int(NumBackClipRects) * 8)))
+// GetDrawableInfoReply represents the data returned from a GetDrawableInfo request.
 type GetDrawableInfoReply 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
 	DrawableTableIndex uint32
 	DrawableTableStamp uint32
@@ -844,7 +877,7 @@ type GetDrawableInfoReply struct {
 	BackClipRects      []DrmClipRect // size: xgb.Pad((int(NumBackClipRects) * 8))
 }
 
-// Waits and reads reply data from request GetDrawableInfo
+// Reply blocks and returns the reply data for a GetDrawableInfo request.
 func (cook GetDrawableInfoCookie) Reply() (*GetDrawableInfoReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -856,7 +889,7 @@ func (cook GetDrawableInfoCookie) Reply() (*GetDrawableInfoReply, error) {
 	return getDrawableInfoReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetDrawableInfo
+// getDrawableInfoReply reads a byte slice into a GetDrawableInfoReply value.
 func getDrawableInfoReply(buf []byte) *GetDrawableInfoReply {
 	v := new(GetDrawableInfoReply)
 	b := 1 // skip reply determinant
@@ -909,6 +942,7 @@ func getDrawableInfoReply(buf []byte) *GetDrawableInfoReply {
 }
 
 // Write request to wire for GetDrawableInfo
+// getDrawableInfoRequest writes a GetDrawableInfo request to a byte slice.
 func getDrawableInfoRequest(c *xgb.Conn, Screen uint32, Drawable uint32) []byte {
 	size := 12
 	b := 0
@@ -932,29 +966,31 @@ func getDrawableInfoRequest(c *xgb.Conn, Screen uint32, Drawable uint32) []byte
 	return buf
 }
 
-// Request GetDeviceInfo
-// size: 8
+// GetDeviceInfoCookie is a cookie used only for GetDeviceInfo requests.
 type GetDeviceInfoCookie struct {
 	*xgb.Cookie
 }
 
+// GetDeviceInfo sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetDeviceInfoCookie.Reply()
 func GetDeviceInfo(c *xgb.Conn, Screen uint32) GetDeviceInfoCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getDeviceInfoRequest(c, Screen), cookie)
 	return GetDeviceInfoCookie{cookie}
 }
 
+// GetDeviceInfoUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetDeviceInfoUnchecked(c *xgb.Conn, Screen uint32) GetDeviceInfoCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getDeviceInfoRequest(c, Screen), cookie)
 	return GetDeviceInfoCookie{cookie}
 }
 
-// Request reply for GetDeviceInfo
-// size: (32 + xgb.Pad((int(DevicePrivateSize) * 4)))
+// GetDeviceInfoReply represents the data returned from a GetDeviceInfo request.
 type GetDeviceInfoReply 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
 	FramebufferHandleLow    uint32
 	FramebufferHandleHigh   uint32
@@ -965,7 +1001,7 @@ type GetDeviceInfoReply struct {
 	DevicePrivate           []uint32 // size: xgb.Pad((int(DevicePrivateSize) * 4))
 }
 
-// Waits and reads reply data from request GetDeviceInfo
+// Reply blocks and returns the reply data for a GetDeviceInfo request.
 func (cook GetDeviceInfoCookie) Reply() (*GetDeviceInfoReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -977,7 +1013,7 @@ func (cook GetDeviceInfoCookie) Reply() (*GetDeviceInfoReply, error) {
 	return getDeviceInfoReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetDeviceInfo
+// getDeviceInfoReply reads a byte slice into a GetDeviceInfoReply value.
 func getDeviceInfoReply(buf []byte) *GetDeviceInfoReply {
 	v := new(GetDeviceInfoReply)
 	b := 1 // skip reply determinant
@@ -1019,6 +1055,7 @@ func getDeviceInfoReply(buf []byte) *GetDeviceInfoReply {
 }
 
 // Write request to wire for GetDeviceInfo
+// getDeviceInfoRequest writes a GetDeviceInfo request to a byte slice.
 func getDeviceInfoRequest(c *xgb.Conn, Screen uint32) []byte {
 	size := 8
 	b := 0
@@ -1039,34 +1076,36 @@ func getDeviceInfoRequest(c *xgb.Conn, Screen uint32) []byte {
 	return buf
 }
 
-// Request AuthConnection
-// size: 12
+// AuthConnectionCookie is a cookie used only for AuthConnection requests.
 type AuthConnectionCookie struct {
 	*xgb.Cookie
 }
 
+// AuthConnection sends a checked request.
+// If an error occurs, it will be returned with the reply by calling AuthConnectionCookie.Reply()
 func AuthConnection(c *xgb.Conn, Screen uint32, Magic uint32) AuthConnectionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(authConnectionRequest(c, Screen, Magic), cookie)
 	return AuthConnectionCookie{cookie}
 }
 
+// AuthConnectionUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func AuthConnectionUnchecked(c *xgb.Conn, Screen uint32, Magic uint32) AuthConnectionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(authConnectionRequest(c, Screen, Magic), cookie)
 	return AuthConnectionCookie{cookie}
 }
 
-// Request reply for AuthConnection
-// size: 12
+// AuthConnectionReply represents the data returned from a AuthConnection request.
 type AuthConnectionReply 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
 	Authenticated uint32
 }
 
-// Waits and reads reply data from request AuthConnection
+// Reply blocks and returns the reply data for a AuthConnection request.
 func (cook AuthConnectionCookie) Reply() (*AuthConnectionReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -1078,7 +1117,7 @@ func (cook AuthConnectionCookie) Reply() (*AuthConnectionReply, error) {
 	return authConnectionReply(buf), nil
 }
 
-// Read reply into structure from buffer for AuthConnection
+// authConnectionReply reads a byte slice into a AuthConnectionReply value.
 func authConnectionReply(buf []byte) *AuthConnectionReply {
 	v := new(AuthConnectionReply)
 	b := 1 // skip reply determinant
@@ -1098,6 +1137,7 @@ func authConnectionReply(buf []byte) *AuthConnectionReply {
 }
 
 // Write request to wire for AuthConnection
+// authConnectionRequest writes a AuthConnection request to a byte slice.
 func authConnectionRequest(c *xgb.Conn, Screen uint32, Magic uint32) []byte {
 	size := 12
 	b := 0