better docs

1 files changed, 165 insertions, 124 deletions

diff --git a/nexgb/dri2/dri2.go b/nexgb/dri2/dri2.go
index c875111..b6398e1 100644
--- a/nexgb/dri2/dri2.go
+++ b/nexgb/dri2/dri2.go
@@ -2,7 +2,7 @@
 package dri2
 
 /*
-	This file was generated by dri2.xml on May 10 2012 8:04:31pm EDT.
+	This file was generated by dri2.xml on May 10 2012 11:56:18pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -40,14 +40,6 @@ func init() {
 	xgb.NewExtErrorFuncs["DRI2"] = make(map[int]xgb.NewErrorFun)
 }
 
-// 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,6 +56,14 @@ func init() {
 
 // 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'
+
 const (
 	AttachmentBufferFrontLeft      = 0
 	AttachmentBufferBackLeft       = 1
@@ -89,8 +89,6 @@ const (
 	EventTypeFlipComplete     = 3
 )
 
-// 'DRI2Buffer' struct definition
-// Size: 20
 type DRI2Buffer struct {
 	Attachment uint32
 	Name       uint32
@@ -99,7 +97,7 @@ type DRI2Buffer struct {
 	Flags      uint32
 }
 
-// Struct read DRI2Buffer
+// DRI2BufferRead reads a byte slice into a DRI2Buffer value.
 func DRI2BufferRead(buf []byte, v *DRI2Buffer) int {
 	b := 0
 
@@ -121,7 +119,7 @@ func DRI2BufferRead(buf []byte, v *DRI2Buffer) int {
 	return b
 }
 
-// Struct list read DRI2Buffer
+// DRI2BufferReadList reads a byte slice into a list of DRI2Buffer values.
 func DRI2BufferReadList(buf []byte, dest []DRI2Buffer) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -131,7 +129,7 @@ func DRI2BufferReadList(buf []byte, dest []DRI2Buffer) int {
 	return xgb.Pad(b)
 }
 
-// Struct write DRI2Buffer
+// Bytes writes a DRI2Buffer value to a byte slice.
 func (v DRI2Buffer) Bytes() []byte {
 	buf := make([]byte, 20)
 	b := 0
@@ -154,7 +152,7 @@ func (v DRI2Buffer) Bytes() []byte {
 	return buf
 }
 
-// Write struct list DRI2Buffer
+// DRI2BufferListBytes writes a list of %s(MISSING) values to a byte slice.
 func DRI2BufferListBytes(buf []byte, list []DRI2Buffer) int {
 	b := 0
 	var structBytes []byte
@@ -166,14 +164,12 @@ func DRI2BufferListBytes(buf []byte, list []DRI2Buffer) int {
 	return b
 }
 
-// 'AttachFormat' struct definition
-// Size: 8
 type AttachFormat struct {
 	Attachment uint32
 	Format     uint32
 }
 
-// Struct read AttachFormat
+// AttachFormatRead reads a byte slice into a AttachFormat value.
 func AttachFormatRead(buf []byte, v *AttachFormat) int {
 	b := 0
 
@@ -186,7 +182,7 @@ func AttachFormatRead(buf []byte, v *AttachFormat) int {
 	return b
 }
 
-// Struct list read AttachFormat
+// AttachFormatReadList reads a byte slice into a list of AttachFormat values.
 func AttachFormatReadList(buf []byte, dest []AttachFormat) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -196,7 +192,7 @@ func AttachFormatReadList(buf []byte, dest []AttachFormat) int {
 	return xgb.Pad(b)
 }
 
-// Struct write AttachFormat
+// Bytes writes a AttachFormat value to a byte slice.
 func (v AttachFormat) Bytes() []byte {
 	buf := make([]byte, 8)
 	b := 0
@@ -210,7 +206,7 @@ func (v AttachFormat) Bytes() []byte {
 	return buf
 }
 
-// Write struct list AttachFormat
+// AttachFormatListBytes writes a list of %s(MISSING) values to a byte slice.
 func AttachFormatListBytes(buf []byte, list []AttachFormat) int {
 	b := 0
 	var structBytes []byte
@@ -222,9 +218,7 @@ func AttachFormatListBytes(buf []byte, list []AttachFormat) int {
 	return b
 }
 
-// Event definition BufferSwapComplete (0)
-// Size: 32
-
+// BufferSwapComplete is the event number for a BufferSwapCompleteEvent.
 const BufferSwapComplete = 0
 
 type BufferSwapCompleteEvent struct {
@@ -240,7 +234,7 @@ type BufferSwapCompleteEvent struct {
 	Sbc      uint32
 }
 
-// Event read BufferSwapComplete
+// BufferSwapCompleteEventNew constructs a BufferSwapCompleteEvent value that implements xgb.Event from a byte slice.
 func BufferSwapCompleteEventNew(buf []byte) xgb.Event {
 	v := BufferSwapCompleteEvent{}
 	b := 1 // don't read event number
@@ -276,7 +270,7 @@ func BufferSwapCompleteEventNew(buf []byte) xgb.Event {
 	return v
 }
 
-// Event write BufferSwapComplete
+// Bytes writes a BufferSwapCompleteEvent value to a byte slice.
 func (v BufferSwapCompleteEvent) Bytes() []byte {
 	buf := make([]byte, 32)
 	b := 0
@@ -315,12 +309,14 @@ func (v BufferSwapCompleteEvent) Bytes() []byte {
 	return buf
 }
 
-func (v BufferSwapCompleteEvent) ImplementsEvent() {}
-
+// SequenceId returns the sequence id attached to the BufferSwapComplete event.
+// Events without a sequence number (KeymapNotify) return 0.
+// This is mostly used internally.
 func (v BufferSwapCompleteEvent) SequenceId() uint16 {
 	return v.Sequence
 }
 
+// String is a rudimentary string representation of BufferSwapCompleteEvent.
 func (v BufferSwapCompleteEvent) String() string {
 	fieldVals := make([]string, 0, 9)
 	fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence))
@@ -338,9 +334,7 @@ func init() {
 	xgb.NewExtEventFuncs["DRI2"][0] = BufferSwapCompleteEventNew
 }
 
-// Event definition InvalidateBuffers (1)
-// Size: 32
-
+// InvalidateBuffers is the event number for a InvalidateBuffersEvent.
 const InvalidateBuffers = 1
 
 type InvalidateBuffersEvent struct {
@@ -349,7 +343,7 @@ type InvalidateBuffersEvent struct {
 	Drawable xproto.Drawable
 }
 
-// Event read InvalidateBuffers
+// InvalidateBuffersEventNew constructs a InvalidateBuffersEvent value that implements xgb.Event from a byte slice.
 func InvalidateBuffersEventNew(buf []byte) xgb.Event {
 	v := InvalidateBuffersEvent{}
 	b := 1 // don't read event number
@@ -365,7 +359,7 @@ func InvalidateBuffersEventNew(buf []byte) xgb.Event {
 	return v
 }
 
-// Event write InvalidateBuffers
+// Bytes writes a InvalidateBuffersEvent value to a byte slice.
 func (v InvalidateBuffersEvent) Bytes() []byte {
 	buf := make([]byte, 32)
 	b := 0
@@ -384,12 +378,14 @@ func (v InvalidateBuffersEvent) Bytes() []byte {
 	return buf
 }
 
-func (v InvalidateBuffersEvent) ImplementsEvent() {}
-
+// SequenceId returns the sequence id attached to the InvalidateBuffers event.
+// Events without a sequence number (KeymapNotify) return 0.
+// This is mostly used internally.
 func (v InvalidateBuffersEvent) SequenceId() uint16 {
 	return v.Sequence
 }
 
+// String is a rudimentary string representation of InvalidateBuffersEvent.
 func (v InvalidateBuffersEvent) String() string {
 	fieldVals := make([]string, 0, 2)
 	fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence))
@@ -401,35 +397,37 @@ func init() {
 	xgb.NewExtEventFuncs["DRI2"][1] = InvalidateBuffersEventNew
 }
 
-// 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, MajorVersion uint32, MinorVersion uint32) QueryVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryVersionRequest(c, MajorVersion, MinorVersion), 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, MajorVersion uint32, MinorVersion uint32) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c, MajorVersion, MinorVersion), 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
 	MajorVersion uint32
 	MinorVersion 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 {
@@ -441,7 +439,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
@@ -464,6 +462,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, MajorVersion uint32, MinorVersion uint32) []byte {
 	size := 12
 	b := 0
@@ -487,29 +486,31 @@ func queryVersionRequest(c *xgb.Conn, MajorVersion uint32, MinorVersion uint32)
 	return buf
 }
 
-// Request Connect
-// size: 12
+// ConnectCookie is a cookie used only for Connect requests.
 type ConnectCookie struct {
 	*xgb.Cookie
 }
 
+// Connect sends a checked request.
+// If an error occurs, it will be returned with the reply by calling ConnectCookie.Reply()
 func Connect(c *xgb.Conn, Window xproto.Window, DriverType uint32) ConnectCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(connectRequest(c, Window, DriverType), cookie)
 	return ConnectCookie{cookie}
 }
 
+// ConnectUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func ConnectUnchecked(c *xgb.Conn, Window xproto.Window, DriverType uint32) ConnectCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(connectRequest(c, Window, DriverType), cookie)
 	return ConnectCookie{cookie}
 }
 
-// Request reply for Connect
-// size: (((32 + xgb.Pad((int(DriverNameLength) * 1))) + xgb.Pad(((((int(DriverNameLength) + 3) & -4) - int(DriverNameLength)) * 1))) + xgb.Pad((int(DeviceNameLength) * 1)))
+// ConnectReply represents the data returned from a Connect request.
 type ConnectReply 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
 	DriverNameLength uint32
 	DeviceNameLength uint32
@@ -519,7 +520,7 @@ type ConnectReply struct {
 	DeviceName   string // size: xgb.Pad((int(DeviceNameLength) * 1))
 }
 
-// Waits and reads reply data from request Connect
+// Reply blocks and returns the reply data for a Connect request.
 func (cook ConnectCookie) Reply() (*ConnectReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -531,7 +532,7 @@ func (cook ConnectCookie) Reply() (*ConnectReply, error) {
 	return connectReply(buf), nil
 }
 
-// Read reply into structure from buffer for Connect
+// connectReply reads a byte slice into a ConnectReply value.
 func connectReply(buf []byte) *ConnectReply {
 	v := new(ConnectReply)
 	b := 1 // skip reply determinant
@@ -574,6 +575,7 @@ func connectReply(buf []byte) *ConnectReply {
 }
 
 // Write request to wire for Connect
+// connectRequest writes a Connect request to a byte slice.
 func connectRequest(c *xgb.Conn, Window xproto.Window, DriverType uint32) []byte {
 	size := 12
 	b := 0
@@ -597,34 +599,36 @@ func connectRequest(c *xgb.Conn, Window xproto.Window, DriverType uint32) []byte
 	return buf
 }
 
-// Request Authenticate
-// size: 12
+// AuthenticateCookie is a cookie used only for Authenticate requests.
 type AuthenticateCookie struct {
 	*xgb.Cookie
 }
 
+// Authenticate sends a checked request.
+// If an error occurs, it will be returned with the reply by calling AuthenticateCookie.Reply()
 func Authenticate(c *xgb.Conn, Window xproto.Window, Magic uint32) AuthenticateCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(authenticateRequest(c, Window, Magic), cookie)
 	return AuthenticateCookie{cookie}
 }
 
+// AuthenticateUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func AuthenticateUnchecked(c *xgb.Conn, Window xproto.Window, Magic uint32) AuthenticateCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(authenticateRequest(c, Window, Magic), cookie)
 	return AuthenticateCookie{cookie}
 }
 
-// Request reply for Authenticate
-// size: 12
+// AuthenticateReply represents the data returned from a Authenticate request.
 type AuthenticateReply 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 Authenticate
+// Reply blocks and returns the reply data for a Authenticate request.
 func (cook AuthenticateCookie) Reply() (*AuthenticateReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -636,7 +640,7 @@ func (cook AuthenticateCookie) Reply() (*AuthenticateReply, error) {
 	return authenticateReply(buf), nil
 }
 
-// Read reply into structure from buffer for Authenticate
+// authenticateReply reads a byte slice into a AuthenticateReply value.
 func authenticateReply(buf []byte) *AuthenticateReply {
 	v := new(AuthenticateReply)
 	b := 1 // skip reply determinant
@@ -656,6 +660,7 @@ func authenticateReply(buf []byte) *AuthenticateReply {
 }
 
 // Write request to wire for Authenticate
+// authenticateRequest writes a Authenticate request to a byte slice.
 func authenticateRequest(c *xgb.Conn, Window xproto.Window, Magic uint32) []byte {
 	size := 12
 	b := 0
@@ -679,30 +684,35 @@ func authenticateRequest(c *xgb.Conn, Window xproto.Window, Magic uint32) []byte
 	return buf
 }
 
-// Request CreateDrawable
-// size: 8
+// CreateDrawableCookie is a cookie used only for CreateDrawable requests.
 type CreateDrawableCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for CreateDrawable
+// CreateDrawable sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CreateDrawable(c *xgb.Conn, Drawable xproto.Drawable) CreateDrawableCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(createDrawableRequest(c, Drawable), cookie)
 	return CreateDrawableCookie{cookie}
 }
 
+// CreateDrawableChecked sends a checked request.
+// If an error occurs, it can be retrieved using CreateDrawableCookie.Check()
 func CreateDrawableChecked(c *xgb.Conn, Drawable xproto.Drawable) CreateDrawableCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(createDrawableRequest(c, Drawable), cookie)
 	return CreateDrawableCookie{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 CreateDrawableCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for CreateDrawable
+// createDrawableRequest writes a CreateDrawable request to a byte slice.
 func createDrawableRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	size := 8
 	b := 0
@@ -723,30 +733,35 @@ func createDrawableRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	return buf
 }
 
-// Request DestroyDrawable
-// size: 8
+// 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, Drawable xproto.Drawable) DestroyDrawableCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(destroyDrawableRequest(c, 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, Drawable xproto.Drawable) DestroyDrawableCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(destroyDrawableRequest(c, 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, Drawable xproto.Drawable) []byte {
 	size := 8
 	b := 0
@@ -767,29 +782,31 @@ func destroyDrawableRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	return buf
 }
 
-// Request GetBuffers
-// size: xgb.Pad((12 + xgb.Pad((len(Attachments) * 4))))
+// GetBuffersCookie is a cookie used only for GetBuffers requests.
 type GetBuffersCookie struct {
 	*xgb.Cookie
 }
 
+// GetBuffers sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetBuffersCookie.Reply()
 func GetBuffers(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Attachments []uint32) GetBuffersCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getBuffersRequest(c, Drawable, Count, Attachments), cookie)
 	return GetBuffersCookie{cookie}
 }
 
+// GetBuffersUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetBuffersUnchecked(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Attachments []uint32) GetBuffersCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getBuffersRequest(c, Drawable, Count, Attachments), cookie)
 	return GetBuffersCookie{cookie}
 }
 
-// Request reply for GetBuffers
-// size: (32 + xgb.Pad((int(Count) * 20)))
+// GetBuffersReply represents the data returned from a GetBuffers request.
 type GetBuffersReply 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
 	Width  uint32
 	Height uint32
@@ -798,7 +815,7 @@ type GetBuffersReply struct {
 	Buffers []DRI2Buffer // size: xgb.Pad((int(Count) * 20))
 }
 
-// Waits and reads reply data from request GetBuffers
+// Reply blocks and returns the reply data for a GetBuffers request.
 func (cook GetBuffersCookie) Reply() (*GetBuffersReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -810,7 +827,7 @@ func (cook GetBuffersCookie) Reply() (*GetBuffersReply, error) {
 	return getBuffersReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetBuffers
+// getBuffersReply reads a byte slice into a GetBuffersReply value.
 func getBuffersReply(buf []byte) *GetBuffersReply {
 	v := new(GetBuffersReply)
 	b := 1 // skip reply determinant
@@ -841,6 +858,7 @@ func getBuffersReply(buf []byte) *GetBuffersReply {
 }
 
 // Write request to wire for GetBuffers
+// getBuffersRequest writes a GetBuffers request to a byte slice.
 func getBuffersRequest(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Attachments []uint32) []byte {
 	size := xgb.Pad((12 + xgb.Pad((len(Attachments) * 4))))
 	b := 0
@@ -870,33 +888,35 @@ func getBuffersRequest(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Atta
 	return buf
 }
 
-// Request CopyRegion
-// size: 20
+// CopyRegionCookie is a cookie used only for CopyRegion requests.
 type CopyRegionCookie struct {
 	*xgb.Cookie
 }
 
+// CopyRegion sends a checked request.
+// If an error occurs, it will be returned with the reply by calling CopyRegionCookie.Reply()
 func CopyRegion(c *xgb.Conn, Drawable xproto.Drawable, Region uint32, Dest uint32, Src uint32) CopyRegionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(copyRegionRequest(c, Drawable, Region, Dest, Src), cookie)
 	return CopyRegionCookie{cookie}
 }
 
+// CopyRegionUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CopyRegionUnchecked(c *xgb.Conn, Drawable xproto.Drawable, Region uint32, Dest uint32, Src uint32) CopyRegionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(copyRegionRequest(c, Drawable, Region, Dest, Src), cookie)
 	return CopyRegionCookie{cookie}
 }
 
-// Request reply for CopyRegion
-// size: 8
+// CopyRegionReply represents the data returned from a CopyRegion request.
 type CopyRegionReply 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
 }
 
-// Waits and reads reply data from request CopyRegion
+// Reply blocks and returns the reply data for a CopyRegion request.
 func (cook CopyRegionCookie) Reply() (*CopyRegionReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -908,7 +928,7 @@ func (cook CopyRegionCookie) Reply() (*CopyRegionReply, error) {
 	return copyRegionReply(buf), nil
 }
 
-// Read reply into structure from buffer for CopyRegion
+// copyRegionReply reads a byte slice into a CopyRegionReply value.
 func copyRegionReply(buf []byte) *CopyRegionReply {
 	v := new(CopyRegionReply)
 	b := 1 // skip reply determinant
@@ -925,6 +945,7 @@ func copyRegionReply(buf []byte) *CopyRegionReply {
 }
 
 // Write request to wire for CopyRegion
+// copyRegionRequest writes a CopyRegion request to a byte slice.
 func copyRegionRequest(c *xgb.Conn, Drawable xproto.Drawable, Region uint32, Dest uint32, Src uint32) []byte {
 	size := 20
 	b := 0
@@ -954,29 +975,31 @@ func copyRegionRequest(c *xgb.Conn, Drawable xproto.Drawable, Region uint32, Des
 	return buf
 }
 
-// Request GetBuffersWithFormat
-// size: xgb.Pad((12 + xgb.Pad((len(Attachments) * 8))))
+// GetBuffersWithFormatCookie is a cookie used only for GetBuffersWithFormat requests.
 type GetBuffersWithFormatCookie struct {
 	*xgb.Cookie
 }
 
+// GetBuffersWithFormat sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetBuffersWithFormatCookie.Reply()
 func GetBuffersWithFormat(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Attachments []AttachFormat) GetBuffersWithFormatCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getBuffersWithFormatRequest(c, Drawable, Count, Attachments), cookie)
 	return GetBuffersWithFormatCookie{cookie}
 }
 
+// GetBuffersWithFormatUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetBuffersWithFormatUnchecked(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Attachments []AttachFormat) GetBuffersWithFormatCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getBuffersWithFormatRequest(c, Drawable, Count, Attachments), cookie)
 	return GetBuffersWithFormatCookie{cookie}
 }
 
-// Request reply for GetBuffersWithFormat
-// size: (32 + xgb.Pad((int(Count) * 20)))
+// GetBuffersWithFormatReply represents the data returned from a GetBuffersWithFormat request.
 type GetBuffersWithFormatReply 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
 	Width  uint32
 	Height uint32
@@ -985,7 +1008,7 @@ type GetBuffersWithFormatReply struct {
 	Buffers []DRI2Buffer // size: xgb.Pad((int(Count) * 20))
 }
 
-// Waits and reads reply data from request GetBuffersWithFormat
+// Reply blocks and returns the reply data for a GetBuffersWithFormat request.
 func (cook GetBuffersWithFormatCookie) Reply() (*GetBuffersWithFormatReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -997,7 +1020,7 @@ func (cook GetBuffersWithFormatCookie) Reply() (*GetBuffersWithFormatReply, erro
 	return getBuffersWithFormatReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetBuffersWithFormat
+// getBuffersWithFormatReply reads a byte slice into a GetBuffersWithFormatReply value.
 func getBuffersWithFormatReply(buf []byte) *GetBuffersWithFormatReply {
 	v := new(GetBuffersWithFormatReply)
 	b := 1 // skip reply determinant
@@ -1028,6 +1051,7 @@ func getBuffersWithFormatReply(buf []byte) *GetBuffersWithFormatReply {
 }
 
 // Write request to wire for GetBuffersWithFormat
+// getBuffersWithFormatRequest writes a GetBuffersWithFormat request to a byte slice.
 func getBuffersWithFormatRequest(c *xgb.Conn, Drawable xproto.Drawable, Count uint32, Attachments []AttachFormat) []byte {
 	size := xgb.Pad((12 + xgb.Pad((len(Attachments) * 8))))
 	b := 0
@@ -1053,35 +1077,37 @@ func getBuffersWithFormatRequest(c *xgb.Conn, Drawable xproto.Drawable, Count ui
 	return buf
 }
 
-// Request SwapBuffers
-// size: 32
+// SwapBuffersCookie is a cookie used only for SwapBuffers requests.
 type SwapBuffersCookie struct {
 	*xgb.Cookie
 }
 
+// SwapBuffers sends a checked request.
+// If an error occurs, it will be returned with the reply by calling SwapBuffersCookie.Reply()
 func SwapBuffers(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, TargetMscLo uint32, DivisorHi uint32, DivisorLo uint32, RemainderHi uint32, RemainderLo uint32) SwapBuffersCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(swapBuffersRequest(c, Drawable, TargetMscHi, TargetMscLo, DivisorHi, DivisorLo, RemainderHi, RemainderLo), cookie)
 	return SwapBuffersCookie{cookie}
 }
 
+// SwapBuffersUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func SwapBuffersUnchecked(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, TargetMscLo uint32, DivisorHi uint32, DivisorLo uint32, RemainderHi uint32, RemainderLo uint32) SwapBuffersCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(swapBuffersRequest(c, Drawable, TargetMscHi, TargetMscLo, DivisorHi, DivisorLo, RemainderHi, RemainderLo), cookie)
 	return SwapBuffersCookie{cookie}
 }
 
-// Request reply for SwapBuffers
-// size: 16
+// SwapBuffersReply represents the data returned from a SwapBuffers request.
 type SwapBuffersReply 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
 	SwapHi uint32
 	SwapLo uint32
 }
 
-// Waits and reads reply data from request SwapBuffers
+// Reply blocks and returns the reply data for a SwapBuffers request.
 func (cook SwapBuffersCookie) Reply() (*SwapBuffersReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -1093,7 +1119,7 @@ func (cook SwapBuffersCookie) Reply() (*SwapBuffersReply, error) {
 	return swapBuffersReply(buf), nil
 }
 
-// Read reply into structure from buffer for SwapBuffers
+// swapBuffersReply reads a byte slice into a SwapBuffersReply value.
 func swapBuffersReply(buf []byte) *SwapBuffersReply {
 	v := new(SwapBuffersReply)
 	b := 1 // skip reply determinant
@@ -1116,6 +1142,7 @@ func swapBuffersReply(buf []byte) *SwapBuffersReply {
 }
 
 // Write request to wire for SwapBuffers
+// swapBuffersRequest writes a SwapBuffers request to a byte slice.
 func swapBuffersRequest(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, TargetMscLo uint32, DivisorHi uint32, DivisorLo uint32, RemainderHi uint32, RemainderLo uint32) []byte {
 	size := 32
 	b := 0
@@ -1154,29 +1181,31 @@ func swapBuffersRequest(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint3
 	return buf
 }
 
-// Request GetMSC
-// size: 8
+// GetMSCCookie is a cookie used only for GetMSC requests.
 type GetMSCCookie struct {
 	*xgb.Cookie
 }
 
+// GetMSC sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetMSCCookie.Reply()
 func GetMSC(c *xgb.Conn, Drawable xproto.Drawable) GetMSCCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getMSCRequest(c, Drawable), cookie)
 	return GetMSCCookie{cookie}
 }
 
+// GetMSCUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetMSCUnchecked(c *xgb.Conn, Drawable xproto.Drawable) GetMSCCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getMSCRequest(c, Drawable), cookie)
 	return GetMSCCookie{cookie}
 }
 
-// Request reply for GetMSC
-// size: 32
+// GetMSCReply represents the data returned from a GetMSC request.
 type GetMSCReply 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
 	UstHi uint32
 	UstLo uint32
@@ -1186,7 +1215,7 @@ type GetMSCReply struct {
 	SbcLo uint32
 }
 
-// Waits and reads reply data from request GetMSC
+// Reply blocks and returns the reply data for a GetMSC request.
 func (cook GetMSCCookie) Reply() (*GetMSCReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -1198,7 +1227,7 @@ func (cook GetMSCCookie) Reply() (*GetMSCReply, error) {
 	return getMSCReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetMSC
+// getMSCReply reads a byte slice into a GetMSCReply value.
 func getMSCReply(buf []byte) *GetMSCReply {
 	v := new(GetMSCReply)
 	b := 1 // skip reply determinant
@@ -1233,6 +1262,7 @@ func getMSCReply(buf []byte) *GetMSCReply {
 }
 
 // Write request to wire for GetMSC
+// getMSCRequest writes a GetMSC request to a byte slice.
 func getMSCRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	size := 8
 	b := 0
@@ -1253,29 +1283,31 @@ func getMSCRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	return buf
 }
 
-// Request WaitMSC
-// size: 32
+// WaitMSCCookie is a cookie used only for WaitMSC requests.
 type WaitMSCCookie struct {
 	*xgb.Cookie
 }
 
+// WaitMSC sends a checked request.
+// If an error occurs, it will be returned with the reply by calling WaitMSCCookie.Reply()
 func WaitMSC(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, TargetMscLo uint32, DivisorHi uint32, DivisorLo uint32, RemainderHi uint32, RemainderLo uint32) WaitMSCCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(waitMSCRequest(c, Drawable, TargetMscHi, TargetMscLo, DivisorHi, DivisorLo, RemainderHi, RemainderLo), cookie)
 	return WaitMSCCookie{cookie}
 }
 
+// WaitMSCUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func WaitMSCUnchecked(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, TargetMscLo uint32, DivisorHi uint32, DivisorLo uint32, RemainderHi uint32, RemainderLo uint32) WaitMSCCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(waitMSCRequest(c, Drawable, TargetMscHi, TargetMscLo, DivisorHi, DivisorLo, RemainderHi, RemainderLo), cookie)
 	return WaitMSCCookie{cookie}
 }
 
-// Request reply for WaitMSC
-// size: 32
+// WaitMSCReply represents the data returned from a WaitMSC request.
 type WaitMSCReply 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
 	UstHi uint32
 	UstLo uint32
@@ -1285,7 +1317,7 @@ type WaitMSCReply struct {
 	SbcLo uint32
 }
 
-// Waits and reads reply data from request WaitMSC
+// Reply blocks and returns the reply data for a WaitMSC request.
 func (cook WaitMSCCookie) Reply() (*WaitMSCReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -1297,7 +1329,7 @@ func (cook WaitMSCCookie) Reply() (*WaitMSCReply, error) {
 	return waitMSCReply(buf), nil
 }
 
-// Read reply into structure from buffer for WaitMSC
+// waitMSCReply reads a byte slice into a WaitMSCReply value.
 func waitMSCReply(buf []byte) *WaitMSCReply {
 	v := new(WaitMSCReply)
 	b := 1 // skip reply determinant
@@ -1332,6 +1364,7 @@ func waitMSCReply(buf []byte) *WaitMSCReply {
 }
 
 // Write request to wire for WaitMSC
+// waitMSCRequest writes a WaitMSC request to a byte slice.
 func waitMSCRequest(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, TargetMscLo uint32, DivisorHi uint32, DivisorLo uint32, RemainderHi uint32, RemainderLo uint32) []byte {
 	size := 32
 	b := 0
@@ -1370,29 +1403,31 @@ func waitMSCRequest(c *xgb.Conn, Drawable xproto.Drawable, TargetMscHi uint32, T
 	return buf
 }
 
-// Request WaitSBC
-// size: 16
+// WaitSBCCookie is a cookie used only for WaitSBC requests.
 type WaitSBCCookie struct {
 	*xgb.Cookie
 }
 
+// WaitSBC sends a checked request.
+// If an error occurs, it will be returned with the reply by calling WaitSBCCookie.Reply()
 func WaitSBC(c *xgb.Conn, Drawable xproto.Drawable, TargetSbcHi uint32, TargetSbcLo uint32) WaitSBCCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(waitSBCRequest(c, Drawable, TargetSbcHi, TargetSbcLo), cookie)
 	return WaitSBCCookie{cookie}
 }
 
+// WaitSBCUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func WaitSBCUnchecked(c *xgb.Conn, Drawable xproto.Drawable, TargetSbcHi uint32, TargetSbcLo uint32) WaitSBCCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(waitSBCRequest(c, Drawable, TargetSbcHi, TargetSbcLo), cookie)
 	return WaitSBCCookie{cookie}
 }
 
-// Request reply for WaitSBC
-// size: 32
+// WaitSBCReply represents the data returned from a WaitSBC request.
 type WaitSBCReply 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
 	UstHi uint32
 	UstLo uint32
@@ -1402,7 +1437,7 @@ type WaitSBCReply struct {
 	SbcLo uint32
 }
 
-// Waits and reads reply data from request WaitSBC
+// Reply blocks and returns the reply data for a WaitSBC request.
 func (cook WaitSBCCookie) Reply() (*WaitSBCReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -1414,7 +1449,7 @@ func (cook WaitSBCCookie) Reply() (*WaitSBCReply, error) {
 	return waitSBCReply(buf), nil
 }
 
-// Read reply into structure from buffer for WaitSBC
+// waitSBCReply reads a byte slice into a WaitSBCReply value.
 func waitSBCReply(buf []byte) *WaitSBCReply {
 	v := new(WaitSBCReply)
 	b := 1 // skip reply determinant
@@ -1449,6 +1484,7 @@ func waitSBCReply(buf []byte) *WaitSBCReply {
 }
 
 // Write request to wire for WaitSBC
+// waitSBCRequest writes a WaitSBC request to a byte slice.
 func waitSBCRequest(c *xgb.Conn, Drawable xproto.Drawable, TargetSbcHi uint32, TargetSbcLo uint32) []byte {
 	size := 16
 	b := 0
@@ -1475,30 +1511,35 @@ func waitSBCRequest(c *xgb.Conn, Drawable xproto.Drawable, TargetSbcHi uint32, T
 	return buf
 }
 
-// Request SwapInterval
-// size: 12
+// SwapIntervalCookie is a cookie used only for SwapInterval requests.
 type SwapIntervalCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for SwapInterval
+// SwapInterval sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func SwapInterval(c *xgb.Conn, Drawable xproto.Drawable, Interval uint32) SwapIntervalCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(swapIntervalRequest(c, Drawable, Interval), cookie)
 	return SwapIntervalCookie{cookie}
 }
 
+// SwapIntervalChecked sends a checked request.
+// If an error occurs, it can be retrieved using SwapIntervalCookie.Check()
 func SwapIntervalChecked(c *xgb.Conn, Drawable xproto.Drawable, Interval uint32) SwapIntervalCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(swapIntervalRequest(c, Drawable, Interval), cookie)
 	return SwapIntervalCookie{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 SwapIntervalCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for SwapInterval
+// swapIntervalRequest writes a SwapInterval request to a byte slice.
 func swapIntervalRequest(c *xgb.Conn, Drawable xproto.Drawable, Interval uint32) []byte {
 	size := 12
 	b := 0