better docs

1 files changed, 53 insertions, 45 deletions

diff --git a/nexgb/res/res.go b/nexgb/res/res.go
index e81fa96..ccc6192 100644
--- a/nexgb/res/res.go
+++ b/nexgb/res/res.go
@@ -2,7 +2,7 @@
 package res
 
 /*
-	This file was generated by res.xml on May 10 2012 8:04:32pm EDT.
+	This file was generated by res.xml on May 10 2012 11:56:19pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -64,14 +64,12 @@ func init() {
 
 // Skipping definition for base type 'Char'
 
-// 'Client' struct definition
-// Size: 8
 type Client struct {
 	ResourceBase uint32
 	ResourceMask uint32
 }
 
-// Struct read Client
+// ClientRead reads a byte slice into a Client value.
 func ClientRead(buf []byte, v *Client) int {
 	b := 0
 
@@ -84,7 +82,7 @@ func ClientRead(buf []byte, v *Client) int {
 	return b
 }
 
-// Struct list read Client
+// ClientReadList reads a byte slice into a list of Client values.
 func ClientReadList(buf []byte, dest []Client) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -94,7 +92,7 @@ func ClientReadList(buf []byte, dest []Client) int {
 	return xgb.Pad(b)
 }
 
-// Struct write Client
+// Bytes writes a Client value to a byte slice.
 func (v Client) Bytes() []byte {
 	buf := make([]byte, 8)
 	b := 0
@@ -108,7 +106,7 @@ func (v Client) Bytes() []byte {
 	return buf
 }
 
-// Write struct list Client
+// ClientListBytes writes a list of %s(MISSING) values to a byte slice.
 func ClientListBytes(buf []byte, list []Client) int {
 	b := 0
 	var structBytes []byte
@@ -120,14 +118,12 @@ func ClientListBytes(buf []byte, list []Client) int {
 	return b
 }
 
-// 'Type' struct definition
-// Size: 8
 type Type struct {
 	ResourceType xproto.Atom
 	Count        uint32
 }
 
-// Struct read Type
+// TypeRead reads a byte slice into a Type value.
 func TypeRead(buf []byte, v *Type) int {
 	b := 0
 
@@ -140,7 +136,7 @@ func TypeRead(buf []byte, v *Type) int {
 	return b
 }
 
-// Struct list read Type
+// TypeReadList reads a byte slice into a list of Type values.
 func TypeReadList(buf []byte, dest []Type) int {
 	b := 0
 	for i := 0; i < len(dest); i++ {
@@ -150,7 +146,7 @@ func TypeReadList(buf []byte, dest []Type) int {
 	return xgb.Pad(b)
 }
 
-// Struct write Type
+// Bytes writes a Type value to a byte slice.
 func (v Type) Bytes() []byte {
 	buf := make([]byte, 8)
 	b := 0
@@ -164,7 +160,7 @@ func (v Type) Bytes() []byte {
 	return buf
 }
 
-// Write struct list Type
+// TypeListBytes writes a list of %s(MISSING) values to a byte slice.
 func TypeListBytes(buf []byte, list []Type) int {
 	b := 0
 	var structBytes []byte
@@ -176,35 +172,37 @@ func TypeListBytes(buf []byte, list []Type) int {
 	return b
 }
 
-// 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, ClientMajor byte, ClientMinor byte) QueryVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryVersionRequest(c, ClientMajor, ClientMinor), 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, ClientMajor byte, ClientMinor byte) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c, ClientMajor, ClientMinor), 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
 	ServerMajor uint16
 	ServerMinor 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 {
@@ -216,7 +214,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
@@ -239,6 +237,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, ClientMajor byte, ClientMinor byte) []byte {
 	size := 8
 	b := 0
@@ -262,36 +261,38 @@ func queryVersionRequest(c *xgb.Conn, ClientMajor byte, ClientMinor byte) []byte
 	return buf
 }
 
-// Request QueryClients
-// size: 4
+// QueryClientsCookie is a cookie used only for QueryClients requests.
 type QueryClientsCookie struct {
 	*xgb.Cookie
 }
 
+// QueryClients sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryClientsCookie.Reply()
 func QueryClients(c *xgb.Conn) QueryClientsCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryClientsRequest(c), cookie)
 	return QueryClientsCookie{cookie}
 }
 
+// QueryClientsUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryClientsUnchecked(c *xgb.Conn) QueryClientsCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryClientsRequest(c), cookie)
 	return QueryClientsCookie{cookie}
 }
 
-// Request reply for QueryClients
-// size: (32 + xgb.Pad((int(NumClients) * 8)))
+// QueryClientsReply represents the data returned from a QueryClients request.
 type QueryClientsReply 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
 	NumClients uint32
 	// padding: 20 bytes
 	Clients []Client // size: xgb.Pad((int(NumClients) * 8))
 }
 
-// Waits and reads reply data from request QueryClients
+// Reply blocks and returns the reply data for a QueryClients request.
 func (cook QueryClientsCookie) Reply() (*QueryClientsReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -303,7 +304,7 @@ func (cook QueryClientsCookie) Reply() (*QueryClientsReply, error) {
 	return queryClientsReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryClients
+// queryClientsReply reads a byte slice into a QueryClientsReply value.
 func queryClientsReply(buf []byte) *QueryClientsReply {
 	v := new(QueryClientsReply)
 	b := 1 // skip reply determinant
@@ -328,6 +329,7 @@ func queryClientsReply(buf []byte) *QueryClientsReply {
 }
 
 // Write request to wire for QueryClients
+// queryClientsRequest writes a QueryClients request to a byte slice.
 func queryClientsRequest(c *xgb.Conn) []byte {
 	size := 4
 	b := 0
@@ -345,36 +347,38 @@ func queryClientsRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request QueryClientResources
-// size: 8
+// QueryClientResourcesCookie is a cookie used only for QueryClientResources requests.
 type QueryClientResourcesCookie struct {
 	*xgb.Cookie
 }
 
+// QueryClientResources sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryClientResourcesCookie.Reply()
 func QueryClientResources(c *xgb.Conn, Xid uint32) QueryClientResourcesCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryClientResourcesRequest(c, Xid), cookie)
 	return QueryClientResourcesCookie{cookie}
 }
 
+// QueryClientResourcesUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryClientResourcesUnchecked(c *xgb.Conn, Xid uint32) QueryClientResourcesCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryClientResourcesRequest(c, Xid), cookie)
 	return QueryClientResourcesCookie{cookie}
 }
 
-// Request reply for QueryClientResources
-// size: (32 + xgb.Pad((int(NumTypes) * 8)))
+// QueryClientResourcesReply represents the data returned from a QueryClientResources request.
 type QueryClientResourcesReply 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
 	NumTypes uint32
 	// padding: 20 bytes
 	Types []Type // size: xgb.Pad((int(NumTypes) * 8))
 }
 
-// Waits and reads reply data from request QueryClientResources
+// Reply blocks and returns the reply data for a QueryClientResources request.
 func (cook QueryClientResourcesCookie) Reply() (*QueryClientResourcesReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -386,7 +390,7 @@ func (cook QueryClientResourcesCookie) Reply() (*QueryClientResourcesReply, erro
 	return queryClientResourcesReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryClientResources
+// queryClientResourcesReply reads a byte slice into a QueryClientResourcesReply value.
 func queryClientResourcesReply(buf []byte) *QueryClientResourcesReply {
 	v := new(QueryClientResourcesReply)
 	b := 1 // skip reply determinant
@@ -411,6 +415,7 @@ func queryClientResourcesReply(buf []byte) *QueryClientResourcesReply {
 }
 
 // Write request to wire for QueryClientResources
+// queryClientResourcesRequest writes a QueryClientResources request to a byte slice.
 func queryClientResourcesRequest(c *xgb.Conn, Xid uint32) []byte {
 	size := 8
 	b := 0
@@ -431,35 +436,37 @@ func queryClientResourcesRequest(c *xgb.Conn, Xid uint32) []byte {
 	return buf
 }
 
-// Request QueryClientPixmapBytes
-// size: 8
+// QueryClientPixmapBytesCookie is a cookie used only for QueryClientPixmapBytes requests.
 type QueryClientPixmapBytesCookie struct {
 	*xgb.Cookie
 }
 
+// QueryClientPixmapBytes sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryClientPixmapBytesCookie.Reply()
 func QueryClientPixmapBytes(c *xgb.Conn, Xid uint32) QueryClientPixmapBytesCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryClientPixmapBytesRequest(c, Xid), cookie)
 	return QueryClientPixmapBytesCookie{cookie}
 }
 
+// QueryClientPixmapBytesUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryClientPixmapBytesUnchecked(c *xgb.Conn, Xid uint32) QueryClientPixmapBytesCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryClientPixmapBytesRequest(c, Xid), cookie)
 	return QueryClientPixmapBytesCookie{cookie}
 }
 
-// Request reply for QueryClientPixmapBytes
-// size: 16
+// QueryClientPixmapBytesReply represents the data returned from a QueryClientPixmapBytes request.
 type QueryClientPixmapBytesReply 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
 	Bytes         uint32
 	BytesOverflow uint32
 }
 
-// Waits and reads reply data from request QueryClientPixmapBytes
+// Reply blocks and returns the reply data for a QueryClientPixmapBytes request.
 func (cook QueryClientPixmapBytesCookie) Reply() (*QueryClientPixmapBytesReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -471,7 +478,7 @@ func (cook QueryClientPixmapBytesCookie) Reply() (*QueryClientPixmapBytesReply,
 	return queryClientPixmapBytesReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryClientPixmapBytes
+// queryClientPixmapBytesReply reads a byte slice into a QueryClientPixmapBytesReply value.
 func queryClientPixmapBytesReply(buf []byte) *QueryClientPixmapBytesReply {
 	v := new(QueryClientPixmapBytesReply)
 	b := 1 // skip reply determinant
@@ -494,6 +501,7 @@ func queryClientPixmapBytesReply(buf []byte) *QueryClientPixmapBytesReply {
 }
 
 // Write request to wire for QueryClientPixmapBytes
+// queryClientPixmapBytesRequest writes a QueryClientPixmapBytes request to a byte slice.
 func queryClientPixmapBytesRequest(c *xgb.Conn, Xid uint32) []byte {
 	size := 8
 	b := 0