better docs

1 files changed, 99 insertions, 77 deletions

diff --git a/nexgb/record/record.go b/nexgb/record/record.go
index 740353d..28b268e 100644
--- a/nexgb/record/record.go
+++ b/nexgb/record/record.go
@@ -2,7 +2,7 @@
 package record
 
 /*
-	This file was generated by record.xml on May 10 2012 8:04:32pm EDT.
+	This file was generated by record.xml on May 10 2012 11:56:19pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -90,14 +90,12 @@ type ElementHeader byte
 
 type ClientSpec uint32
 
-// 'Range8' struct definition
-// Size: 2
 type Range8 struct {
 	First byte
 	Last  byte
 }
 
-// Struct read Range8
+// Range8Read reads a byte slice into a Range8 value.
 func Range8Read(buf []byte, v *Range8) int {
 	b := 0
 
@@ -110,7 +108,7 @@ func Range8Read(buf []byte, v *Range8) int {
 	return b
 }
 
-// Struct list read Range8
+// Range8ReadList reads a byte slice into a list of Range8 values.
 func Range8ReadList(buf []byte, dest []Range8) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -120,7 +118,7 @@ func Range8ReadList(buf []byte, dest []Range8) int {
 	return xgb.Pad(b)
 }
 
-// Struct write Range8
+// Bytes writes a Range8 value to a byte slice.
 func (v Range8) Bytes() []byte {
 	buf := make([]byte, 2)
 	b := 0
@@ -134,7 +132,7 @@ func (v Range8) Bytes() []byte {
 	return buf
 }
 
-// Write struct list Range8
+// Range8ListBytes writes a list of %s(MISSING) values to a byte slice.
 func Range8ListBytes(buf []byte, list []Range8) int {
 	b := 0
 	var structBytes []byte
@@ -146,14 +144,12 @@ func Range8ListBytes(buf []byte, list []Range8) int {
 	return b
 }
 
-// 'Range16' struct definition
-// Size: 4
 type Range16 struct {
 	First uint16
 	Last  uint16
 }
 
-// Struct read Range16
+// Range16Read reads a byte slice into a Range16 value.
 func Range16Read(buf []byte, v *Range16) int {
 	b := 0
 
@@ -166,7 +162,7 @@ func Range16Read(buf []byte, v *Range16) int {
 	return b
 }
 
-// Struct list read Range16
+// Range16ReadList reads a byte slice into a list of Range16 values.
 func Range16ReadList(buf []byte, dest []Range16) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -176,7 +172,7 @@ func Range16ReadList(buf []byte, dest []Range16) int {
 	return xgb.Pad(b)
 }
 
-// Struct write Range16
+// Bytes writes a Range16 value to a byte slice.
 func (v Range16) Bytes() []byte {
 	buf := make([]byte, 4)
 	b := 0
@@ -190,7 +186,7 @@ func (v Range16) Bytes() []byte {
 	return buf
 }
 
-// Write struct list Range16
+// Range16ListBytes writes a list of %s(MISSING) values to a byte slice.
 func Range16ListBytes(buf []byte, list []Range16) int {
 	b := 0
 	var structBytes []byte
@@ -202,14 +198,12 @@ func Range16ListBytes(buf []byte, list []Range16) int {
 	return b
 }
 
-// 'ExtRange' struct definition
-// Size: 6
 type ExtRange struct {
 	Major Range8
 	Minor Range16
 }
 
-// Struct read ExtRange
+// ExtRangeRead reads a byte slice into a ExtRange value.
 func ExtRangeRead(buf []byte, v *ExtRange) int {
 	b := 0
 
@@ -222,7 +216,7 @@ func ExtRangeRead(buf []byte, v *ExtRange) int {
 	return b
 }
 
-// Struct list read ExtRange
+// ExtRangeReadList reads a byte slice into a list of ExtRange values.
 func ExtRangeReadList(buf []byte, dest []ExtRange) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -232,7 +226,7 @@ func ExtRangeReadList(buf []byte, dest []ExtRange) int {
 	return xgb.Pad(b)
 }
 
-// Struct write ExtRange
+// Bytes writes a ExtRange value to a byte slice.
 func (v ExtRange) Bytes() []byte {
 	buf := make([]byte, 6)
 	b := 0
@@ -252,7 +246,7 @@ func (v ExtRange) Bytes() []byte {
 	return buf
 }
 
-// Write struct list ExtRange
+// ExtRangeListBytes writes a list of %s(MISSING) values to a byte slice.
 func ExtRangeListBytes(buf []byte, list []ExtRange) int {
 	b := 0
 	var structBytes []byte
@@ -264,8 +258,6 @@ func ExtRangeListBytes(buf []byte, list []ExtRange) int {
 	return b
 }
 
-// 'Range' struct definition
-// Size: 24
 type Range struct {
 	CoreRequests    Range8
 	CoreReplies     Range8
@@ -278,7 +270,7 @@ type Range struct {
 	ClientDied      bool
 }
 
-// Struct read Range
+// RangeRead reads a byte slice into a Range value.
 func RangeRead(buf []byte, v *Range) int {
 	b := 0
 
@@ -320,7 +312,7 @@ func RangeRead(buf []byte, v *Range) int {
 	return b
 }
 
-// Struct list read Range
+// RangeReadList reads a byte slice into a list of Range values.
 func RangeReadList(buf []byte, dest []Range) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -330,7 +322,7 @@ func RangeReadList(buf []byte, dest []Range) int {
 	return xgb.Pad(b)
 }
 
-// Struct write Range
+// Bytes writes a Range value to a byte slice.
 func (v Range) Bytes() []byte {
 	buf := make([]byte, 24)
 	b := 0
@@ -394,7 +386,7 @@ func (v Range) Bytes() []byte {
 	return buf
 }
 
-// Write struct list Range
+// RangeListBytes writes a list of %s(MISSING) values to a byte slice.
 func RangeListBytes(buf []byte, list []Range) int {
 	b := 0
 	var structBytes []byte
@@ -406,15 +398,13 @@ func RangeListBytes(buf []byte, list []Range) int {
 	return b
 }
 
-// 'ClientInfo' struct definition
-// Size: (8 + xgb.Pad((int(NumRanges) * 24)))
 type ClientInfo struct {
 	ClientResource ClientSpec
 	NumRanges      uint32
 	Ranges         []Range // size: xgb.Pad((int(NumRanges) * 24))
 }
 
-// Struct read ClientInfo
+// ClientInfoRead reads a byte slice into a ClientInfo value.
 func ClientInfoRead(buf []byte, v *ClientInfo) int {
 	b := 0
 
@@ -430,7 +420,7 @@ func ClientInfoRead(buf []byte, v *ClientInfo) int {
 	return b
 }
 
-// Struct list read ClientInfo
+// ClientInfoReadList reads a byte slice into a list of ClientInfo values.
 func ClientInfoReadList(buf []byte, dest []ClientInfo) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -440,7 +430,7 @@ func ClientInfoReadList(buf []byte, dest []ClientInfo) int {
 	return xgb.Pad(b)
 }
 
-// Struct write ClientInfo
+// Bytes writes a ClientInfo value to a byte slice.
 func (v ClientInfo) Bytes() []byte {
 	buf := make([]byte, (8 + xgb.Pad((int(v.NumRanges) * 24))))
 	b := 0
@@ -456,7 +446,7 @@ func (v ClientInfo) Bytes() []byte {
 	return buf
 }
 
-// Write struct list ClientInfo
+// ClientInfoListBytes writes a list of %s(MISSING) values to a byte slice.
 func ClientInfoListBytes(buf []byte, list []ClientInfo) int {
 	b := 0
 	var structBytes []byte
@@ -468,7 +458,7 @@ func ClientInfoListBytes(buf []byte, list []ClientInfo) int {
 	return b
 }
 
-// Struct list size ClientInfo
+// ClientInfoListSize computes the size (bytes) of a list of ClientInfo values.
 func ClientInfoListSize(list []ClientInfo) int {
 	size := 0
 	for _, item := range list {
@@ -477,9 +467,7 @@ func ClientInfoListSize(list []ClientInfo) int {
 	return size
 }
 
-// Error definition BadContext (0)
-// Size: 32
-
+// BadBadContext is the error number for a BadBadContext.
 const BadBadContext = 0
 
 type BadContextError struct {
@@ -488,7 +476,7 @@ type BadContextError struct {
 	InvalidRecord uint32
 }
 
-// Error read BadContext
+// BadContextErrorNew constructs a BadContextError value that implements xgb.Error from a byte slice.
 func BadContextErrorNew(buf []byte) xgb.Error {
 	v := BadContextError{}
 	v.NiceName = "BadContext"
@@ -505,8 +493,8 @@ func BadContextErrorNew(buf []byte) xgb.Error {
 	return v
 }
 
-func (err BadContextError) ImplementsError() {}
-
+// SequenceId returns the sequence id attached to the BadBadContext error.
+// This is mostly used internally.
 func (err BadContextError) SequenceId() uint16 {
 	return err.Sequence
 }
@@ -527,35 +515,37 @@ func init() {
 	xgb.NewExtErrorFuncs["RECORD"][0] = BadContextErrorNew
 }
 
-// Request QueryVersion
-// size: 8
+// 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 uint16, MinorVersion uint16) 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 uint16, MinorVersion uint16) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c, MajorVersion, MinorVersion), cookie)
 	return QueryVersionCookie{cookie}
 }
 
-// Request reply for QueryVersion
-// size: 12
+// 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 uint16
 	MinorVersion uint16
 }
 
-// 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 {
@@ -567,7 +557,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
@@ -590,6 +580,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 uint16, MinorVersion uint16) []byte {
 	size := 8
 	b := 0
@@ -613,30 +604,35 @@ func queryVersionRequest(c *xgb.Conn, MajorVersion uint16, MinorVersion uint16)
 	return buf
 }
 
-// Request CreateContext
-// size: xgb.Pad(((20 + xgb.Pad((int(NumClientSpecs) * 4))) + xgb.Pad((int(NumRanges) * 24))))
+// CreateContextCookie is a cookie used only for CreateContext requests.
 type CreateContextCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for CreateContext
+// CreateContext sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CreateContext(c *xgb.Conn, Context Context, ElementHeader ElementHeader, NumClientSpecs uint32, NumRanges uint32, ClientSpecs []ClientSpec, Ranges []Range) CreateContextCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(createContextRequest(c, Context, ElementHeader, NumClientSpecs, NumRanges, ClientSpecs, Ranges), cookie)
 	return CreateContextCookie{cookie}
 }
 
+// CreateContextChecked sends a checked request.
+// If an error occurs, it can be retrieved using CreateContextCookie.Check()
 func CreateContextChecked(c *xgb.Conn, Context Context, ElementHeader ElementHeader, NumClientSpecs uint32, NumRanges uint32, ClientSpecs []ClientSpec, Ranges []Range) CreateContextCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(createContextRequest(c, Context, ElementHeader, NumClientSpecs, NumRanges, ClientSpecs, Ranges), cookie)
 	return CreateContextCookie{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 CreateContextCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for CreateContext
+// createContextRequest writes a CreateContext request to a byte slice.
 func createContextRequest(c *xgb.Conn, Context Context, ElementHeader ElementHeader, NumClientSpecs uint32, NumRanges uint32, ClientSpecs []ClientSpec, Ranges []Range) []byte {
 	size := xgb.Pad(((20 + xgb.Pad((int(NumClientSpecs) * 4))) + xgb.Pad((int(NumRanges) * 24))))
 	b := 0
@@ -676,30 +672,35 @@ func createContextRequest(c *xgb.Conn, Context Context, ElementHeader ElementHea
 	return buf
 }
 
-// Request RegisterClients
-// size: xgb.Pad(((20 + xgb.Pad((int(NumClientSpecs) * 4))) + xgb.Pad((int(NumRanges) * 24))))
+// RegisterClientsCookie is a cookie used only for RegisterClients requests.
 type RegisterClientsCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for RegisterClients
+// RegisterClients sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func RegisterClients(c *xgb.Conn, Context Context, ElementHeader ElementHeader, NumClientSpecs uint32, NumRanges uint32, ClientSpecs []ClientSpec, Ranges []Range) RegisterClientsCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(registerClientsRequest(c, Context, ElementHeader, NumClientSpecs, NumRanges, ClientSpecs, Ranges), cookie)
 	return RegisterClientsCookie{cookie}
 }
 
+// RegisterClientsChecked sends a checked request.
+// If an error occurs, it can be retrieved using RegisterClientsCookie.Check()
 func RegisterClientsChecked(c *xgb.Conn, Context Context, ElementHeader ElementHeader, NumClientSpecs uint32, NumRanges uint32, ClientSpecs []ClientSpec, Ranges []Range) RegisterClientsCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(registerClientsRequest(c, Context, ElementHeader, NumClientSpecs, NumRanges, ClientSpecs, Ranges), cookie)
 	return RegisterClientsCookie{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 RegisterClientsCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for RegisterClients
+// registerClientsRequest writes a RegisterClients request to a byte slice.
 func registerClientsRequest(c *xgb.Conn, Context Context, ElementHeader ElementHeader, NumClientSpecs uint32, NumRanges uint32, ClientSpecs []ClientSpec, Ranges []Range) []byte {
 	size := xgb.Pad(((20 + xgb.Pad((int(NumClientSpecs) * 4))) + xgb.Pad((int(NumRanges) * 24))))
 	b := 0
@@ -739,30 +740,35 @@ func registerClientsRequest(c *xgb.Conn, Context Context, ElementHeader ElementH
 	return buf
 }
 
-// Request UnregisterClients
-// size: xgb.Pad((12 + xgb.Pad((int(NumClientSpecs) * 4))))
+// UnregisterClientsCookie is a cookie used only for UnregisterClients requests.
 type UnregisterClientsCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for UnregisterClients
+// UnregisterClients sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func UnregisterClients(c *xgb.Conn, Context Context, NumClientSpecs uint32, ClientSpecs []ClientSpec) UnregisterClientsCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(unregisterClientsRequest(c, Context, NumClientSpecs, ClientSpecs), cookie)
 	return UnregisterClientsCookie{cookie}
 }
 
+// UnregisterClientsChecked sends a checked request.
+// If an error occurs, it can be retrieved using UnregisterClientsCookie.Check()
 func UnregisterClientsChecked(c *xgb.Conn, Context Context, NumClientSpecs uint32, ClientSpecs []ClientSpec) UnregisterClientsCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(unregisterClientsRequest(c, Context, NumClientSpecs, ClientSpecs), cookie)
 	return UnregisterClientsCookie{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 UnregisterClientsCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for UnregisterClients
+// unregisterClientsRequest writes a UnregisterClients request to a byte slice.
 func unregisterClientsRequest(c *xgb.Conn, Context Context, NumClientSpecs uint32, ClientSpecs []ClientSpec) []byte {
 	size := xgb.Pad((12 + xgb.Pad((int(NumClientSpecs) * 4))))
 	b := 0
@@ -792,29 +798,31 @@ func unregisterClientsRequest(c *xgb.Conn, Context Context, NumClientSpecs uint3
 	return buf
 }
 
-// Request GetContext
-// size: 8
+// GetContextCookie is a cookie used only for GetContext requests.
 type GetContextCookie struct {
 	*xgb.Cookie
 }
 
+// GetContext sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetContextCookie.Reply()
 func GetContext(c *xgb.Conn, Context Context) GetContextCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getContextRequest(c, Context), cookie)
 	return GetContextCookie{cookie}
 }
 
+// GetContextUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetContextUnchecked(c *xgb.Conn, Context Context) GetContextCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getContextRequest(c, Context), cookie)
 	return GetContextCookie{cookie}
 }
 
-// Request reply for GetContext
-// size: (32 + ClientInfoListSize(InterceptedClients))
+// GetContextReply represents the data returned from a GetContext request.
 type GetContextReply struct {
-	Sequence      uint16
-	Length        uint32
+	Sequence      uint16 // sequence number of the request for this reply
+	Length        uint32 // number of bytes in this reply
 	Enabled       bool
 	ElementHeader ElementHeader
 	// padding: 3 bytes
@@ -823,7 +831,7 @@ type GetContextReply struct {
 	InterceptedClients []ClientInfo // size: ClientInfoListSize(InterceptedClients)
 }
 
-// Waits and reads reply data from request GetContext
+// Reply blocks and returns the reply data for a GetContext request.
 func (cook GetContextCookie) Reply() (*GetContextReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -835,7 +843,7 @@ func (cook GetContextCookie) Reply() (*GetContextReply, error) {
 	return getContextReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetContext
+// getContextReply reads a byte slice into a GetContextReply value.
 func getContextReply(buf []byte) *GetContextReply {
 	v := new(GetContextReply)
 	b := 1 // skip reply determinant
@@ -870,6 +878,7 @@ func getContextReply(buf []byte) *GetContextReply {
 }
 
 // Write request to wire for GetContext
+// getContextRequest writes a GetContext request to a byte slice.
 func getContextRequest(c *xgb.Conn, Context Context) []byte {
 	size := 8
 	b := 0
@@ -890,29 +899,31 @@ func getContextRequest(c *xgb.Conn, Context Context) []byte {
 	return buf
 }
 
-// Request EnableContext
-// size: 8
+// EnableContextCookie is a cookie used only for EnableContext requests.
 type EnableContextCookie struct {
 	*xgb.Cookie
 }
 
+// EnableContext sends a checked request.
+// If an error occurs, it will be returned with the reply by calling EnableContextCookie.Reply()
 func EnableContext(c *xgb.Conn, Context Context) EnableContextCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(enableContextRequest(c, Context), cookie)
 	return EnableContextCookie{cookie}
 }
 
+// EnableContextUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func EnableContextUnchecked(c *xgb.Conn, Context Context) EnableContextCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(enableContextRequest(c, Context), cookie)
 	return EnableContextCookie{cookie}
 }
 
-// Request reply for EnableContext
-// size: (32 + xgb.Pad(((int(Length) * 4) * 1)))
+// EnableContextReply represents the data returned from a EnableContext request.
 type EnableContextReply struct {
-	Sequence      uint16
-	Length        uint32
+	Sequence      uint16 // sequence number of the request for this reply
+	Length        uint32 // number of bytes in this reply
 	Category      byte
 	ElementHeader ElementHeader
 	ClientSwapped bool
@@ -924,7 +935,7 @@ type EnableContextReply struct {
 	Data []byte // size: xgb.Pad(((int(Length) * 4) * 1))
 }
 
-// Waits and reads reply data from request EnableContext
+// Reply blocks and returns the reply data for a EnableContext request.
 func (cook EnableContextCookie) Reply() (*EnableContextReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -936,7 +947,7 @@ func (cook EnableContextCookie) Reply() (*EnableContextReply, error) {
 	return enableContextReply(buf), nil
 }
 
-// Read reply into structure from buffer for EnableContext
+// enableContextReply reads a byte slice into a EnableContextReply value.
 func enableContextReply(buf []byte) *EnableContextReply {
 	v := new(EnableContextReply)
 	b := 1 // skip reply determinant
@@ -981,6 +992,7 @@ func enableContextReply(buf []byte) *EnableContextReply {
 }
 
 // Write request to wire for EnableContext
+// enableContextRequest writes a EnableContext request to a byte slice.
 func enableContextRequest(c *xgb.Conn, Context Context) []byte {
 	size := 8
 	b := 0
@@ -1001,30 +1013,35 @@ func enableContextRequest(c *xgb.Conn, Context Context) []byte {
 	return buf
 }
 
-// Request DisableContext
-// size: 8
+// DisableContextCookie is a cookie used only for DisableContext requests.
 type DisableContextCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for DisableContext
+// DisableContext sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func DisableContext(c *xgb.Conn, Context Context) DisableContextCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(disableContextRequest(c, Context), cookie)
 	return DisableContextCookie{cookie}
 }
 
+// DisableContextChecked sends a checked request.
+// If an error occurs, it can be retrieved using DisableContextCookie.Check()
 func DisableContextChecked(c *xgb.Conn, Context Context) DisableContextCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(disableContextRequest(c, Context), cookie)
 	return DisableContextCookie{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 DisableContextCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for DisableContext
+// disableContextRequest writes a DisableContext request to a byte slice.
 func disableContextRequest(c *xgb.Conn, Context Context) []byte {
 	size := 8
 	b := 0
@@ -1045,30 +1062,35 @@ func disableContextRequest(c *xgb.Conn, Context Context) []byte {
 	return buf
 }
 
-// Request FreeContext
-// size: 8
+// FreeContextCookie is a cookie used only for FreeContext requests.
 type FreeContextCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for FreeContext
+// FreeContext sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func FreeContext(c *xgb.Conn, Context Context) FreeContextCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(freeContextRequest(c, Context), cookie)
 	return FreeContextCookie{cookie}
 }
 
+// FreeContextChecked sends a checked request.
+// If an error occurs, it can be retrieved using FreeContextCookie.Check()
 func FreeContextChecked(c *xgb.Conn, Context Context) FreeContextCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(freeContextRequest(c, Context), cookie)
 	return FreeContextCookie{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 FreeContextCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for FreeContext
+// freeContextRequest writes a FreeContext request to a byte slice.
 func freeContextRequest(c *xgb.Conn, Context Context) []byte {
 	size := 8
 	b := 0