better docs

1 files changed, 55 insertions, 34 deletions

diff --git a/nexgb/damage/damage.go b/nexgb/damage/damage.go
index 8c59f55..1c17501 100644
--- a/nexgb/damage/damage.go
+++ b/nexgb/damage/damage.go
@@ -2,7 +2,7 @@
 package damage
 
 /*
-	This file was generated by damage.xml on May 10 2012 8:04:31pm EDT.
+	This file was generated by damage.xml on May 10 2012 11:56:18pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -82,9 +82,7 @@ func NewDamageId(c *xgb.Conn) (Damage, error) {
 	return Damage(id), nil
 }
 
-// Event definition Notify (0)
-// Size: 32
-
+// Notify is the event number for a NotifyEvent.
 const Notify = 0
 
 type NotifyEvent struct {
@@ -97,7 +95,7 @@ type NotifyEvent struct {
 	Geometry  xproto.Rectangle
 }
 
-// Event read Notify
+// NotifyEventNew constructs a NotifyEvent value that implements xgb.Event from a byte slice.
 func NotifyEventNew(buf []byte) xgb.Event {
 	v := NotifyEvent{}
 	b := 1 // don't read event number
@@ -126,7 +124,7 @@ func NotifyEventNew(buf []byte) xgb.Event {
 	return v
 }
 
-// Event write Notify
+// Bytes writes a NotifyEvent value to a byte slice.
 func (v NotifyEvent) Bytes() []byte {
 	buf := make([]byte, 32)
 	b := 0
@@ -164,12 +162,14 @@ func (v NotifyEvent) Bytes() []byte {
 	return buf
 }
 
-func (v NotifyEvent) ImplementsEvent() {}
-
+// SequenceId returns the sequence id attached to the Notify event.
+// Events without a sequence number (KeymapNotify) return 0.
+// This is mostly used internally.
 func (v NotifyEvent) SequenceId() uint16 {
 	return v.Sequence
 }
 
+// String is a rudimentary string representation of NotifyEvent.
 func (v NotifyEvent) String() string {
 	fieldVals := make([]string, 0, 6)
 	fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence))
@@ -184,9 +184,7 @@ func init() {
 	xgb.NewExtEventFuncs["DAMAGE"][0] = NotifyEventNew
 }
 
-// Error definition BadDamage (0)
-// Size: 32
-
+// BadBadDamage is the error number for a BadBadDamage.
 const BadBadDamage = 0
 
 type BadDamageError struct {
@@ -194,7 +192,7 @@ type BadDamageError struct {
 	NiceName string
 }
 
-// Error read BadDamage
+// BadDamageErrorNew constructs a BadDamageError value that implements xgb.Error from a byte slice.
 func BadDamageErrorNew(buf []byte) xgb.Error {
 	v := BadDamageError{}
 	v.NiceName = "BadDamage"
@@ -208,8 +206,8 @@ func BadDamageErrorNew(buf []byte) xgb.Error {
 	return v
 }
 
-func (err BadDamageError) ImplementsError() {}
-
+// SequenceId returns the sequence id attached to the BadBadDamage error.
+// This is mostly used internally.
 func (err BadDamageError) SequenceId() uint16 {
 	return err.Sequence
 }
@@ -229,36 +227,38 @@ func init() {
 	xgb.NewExtErrorFuncs["DAMAGE"][0] = BadDamageErrorNew
 }
 
-// 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, ClientMajorVersion uint32, ClientMinorVersion uint32) QueryVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryVersionRequest(c, ClientMajorVersion, ClientMinorVersion), 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, ClientMajorVersion uint32, ClientMinorVersion uint32) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c, ClientMajorVersion, ClientMinorVersion), cookie)
 	return QueryVersionCookie{cookie}
 }
 
-// Request reply for QueryVersion
-// size: 32
+// 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
 	// padding: 16 bytes
 }
 
-// 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 {
@@ -270,7 +270,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
@@ -295,6 +295,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, ClientMajorVersion uint32, ClientMinorVersion uint32) []byte {
 	size := 12
 	b := 0
@@ -318,30 +319,35 @@ func queryVersionRequest(c *xgb.Conn, ClientMajorVersion uint32, ClientMinorVers
 	return buf
 }
 
-// Request Create
-// size: 16
+// CreateCookie is a cookie used only for Create requests.
 type CreateCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Create
+// Create sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Create(c *xgb.Conn, Damage Damage, Drawable xproto.Drawable, Level byte) CreateCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(createRequest(c, Damage, Drawable, Level), cookie)
 	return CreateCookie{cookie}
 }
 
+// CreateChecked sends a checked request.
+// If an error occurs, it can be retrieved using CreateCookie.Check()
 func CreateChecked(c *xgb.Conn, Damage Damage, Drawable xproto.Drawable, Level byte) CreateCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(createRequest(c, Damage, Drawable, Level), cookie)
 	return CreateCookie{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 CreateCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Create
+// createRequest writes a Create request to a byte slice.
 func createRequest(c *xgb.Conn, Damage Damage, Drawable xproto.Drawable, Level byte) []byte {
 	size := 16
 	b := 0
@@ -370,30 +376,35 @@ func createRequest(c *xgb.Conn, Damage Damage, Drawable xproto.Drawable, Level b
 	return buf
 }
 
-// Request Destroy
-// size: 8
+// DestroyCookie is a cookie used only for Destroy requests.
 type DestroyCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Destroy
+// Destroy sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Destroy(c *xgb.Conn, Damage Damage) DestroyCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(destroyRequest(c, Damage), cookie)
 	return DestroyCookie{cookie}
 }
 
+// DestroyChecked sends a checked request.
+// If an error occurs, it can be retrieved using DestroyCookie.Check()
 func DestroyChecked(c *xgb.Conn, Damage Damage) DestroyCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(destroyRequest(c, Damage), cookie)
 	return DestroyCookie{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 DestroyCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Destroy
+// destroyRequest writes a Destroy request to a byte slice.
 func destroyRequest(c *xgb.Conn, Damage Damage) []byte {
 	size := 8
 	b := 0
@@ -414,30 +425,35 @@ func destroyRequest(c *xgb.Conn, Damage Damage) []byte {
 	return buf
 }
 
-// Request Subtract
-// size: 16
+// SubtractCookie is a cookie used only for Subtract requests.
 type SubtractCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Subtract
+// Subtract sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Subtract(c *xgb.Conn, Damage Damage, Repair xfixes.Region, Parts xfixes.Region) SubtractCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(subtractRequest(c, Damage, Repair, Parts), cookie)
 	return SubtractCookie{cookie}
 }
 
+// SubtractChecked sends a checked request.
+// If an error occurs, it can be retrieved using SubtractCookie.Check()
 func SubtractChecked(c *xgb.Conn, Damage Damage, Repair xfixes.Region, Parts xfixes.Region) SubtractCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(subtractRequest(c, Damage, Repair, Parts), cookie)
 	return SubtractCookie{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 SubtractCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Subtract
+// subtractRequest writes a Subtract request to a byte slice.
 func subtractRequest(c *xgb.Conn, Damage Damage, Repair xfixes.Region, Parts xfixes.Region) []byte {
 	size := 16
 	b := 0
@@ -464,30 +480,35 @@ func subtractRequest(c *xgb.Conn, Damage Damage, Repair xfixes.Region, Parts xfi
 	return buf
 }
 
-// Request Add
-// size: 12
+// AddCookie is a cookie used only for Add requests.
 type AddCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Add
+// Add sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Add(c *xgb.Conn, Drawable xproto.Drawable, Region xfixes.Region) AddCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(addRequest(c, Drawable, Region), cookie)
 	return AddCookie{cookie}
 }
 
+// AddChecked sends a checked request.
+// If an error occurs, it can be retrieved using AddCookie.Check()
 func AddChecked(c *xgb.Conn, Drawable xproto.Drawable, Region xfixes.Region) AddCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(addRequest(c, Drawable, Region), cookie)
 	return AddCookie{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 AddCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Add
+// addRequest writes a Add request to a byte slice.
 func addRequest(c *xgb.Conn, Drawable xproto.Drawable, Region xfixes.Region) []byte {
 	size := 12
 	b := 0