better docs

nexgb/bigreq/bigreq.go

@@ -2,7 +2,7 @@
 package bigreq
 
 /*
-	This file was generated by bigreq.xml on May 10 2012 8:04:31pm EDT.
+	This file was generated by bigreq.xml on May 10 2012 11:56:18pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -40,6 +40,8 @@ func init() {
 	xgb.NewExtErrorFuncs["BIG-REQUESTS"] = make(map[int]xgb.NewErrorFun)
 }
 
+// Skipping definition for base type 'Float'
+
 // Skipping definition for base type 'Card8'
 
 // Skipping definition for base type 'Int16'
@@ -62,36 +64,36 @@ func init() {
 
 // Skipping definition for base type 'Bool'
 
-// Skipping definition for base type 'Float'
-
-// Request Enable
-// size: 4
+// EnableCookie is a cookie used only for Enable requests.
 type EnableCookie struct {
 	*xgb.Cookie
 }
 
+// Enable sends a checked request.
+// If an error occurs, it will be returned with the reply by calling EnableCookie.Reply()
 func Enable(c *xgb.Conn) EnableCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(enableRequest(c), cookie)
 	return EnableCookie{cookie}
 }
 
+// EnableUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func EnableUnchecked(c *xgb.Conn) EnableCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(enableRequest(c), cookie)
 	return EnableCookie{cookie}
 }
 
-// Request reply for Enable
-// size: 12
+// EnableReply represents the data returned from a Enable request.
 type EnableReply 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
 	MaximumRequestLength uint32
 }
 
-// Waits and reads reply data from request Enable
+// Reply blocks and returns the reply data for a Enable request.
 func (cook EnableCookie) Reply() (*EnableReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -103,7 +105,7 @@ func (cook EnableCookie) Reply() (*EnableReply, error) {
 	return enableReply(buf), nil
 }
 
-// Read reply into structure from buffer for Enable
+// enableReply reads a byte slice into a EnableReply value.
 func enableReply(buf []byte) *EnableReply {
 	v := new(EnableReply)
 	b := 1 // skip reply determinant
@@ -123,6 +125,7 @@ func enableReply(buf []byte) *EnableReply {
 }
 
 // Write request to wire for Enable
+// enableRequest writes a Enable request to a byte slice.
 func enableRequest(c *xgb.Conn) []byte {
 	size := 4
 	b := 0