better docs

1 files changed, 68 insertions, 42 deletions

diff --git a/nexgb/shm/shm.go b/nexgb/shm/shm.go
index d262667..b24be97 100644
--- a/nexgb/shm/shm.go
+++ b/nexgb/shm/shm.go
@@ -2,7 +2,7 @@
 package shm
 
 /*
-	This file was generated by shm.xml on May 10 2012 8:04:32pm EDT.
+	This file was generated by shm.xml on May 10 2012 11:56:19pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -40,6 +40,8 @@ func init() {
 	xgb.NewExtErrorFuncs["MIT-SHM"] = make(map[int]xgb.NewErrorFun)
 }
 
+// Skipping definition for base type 'Int32'
+
 // Skipping definition for base type 'Void'
 
 // Skipping definition for base type 'Byte'
@@ -62,8 +64,6 @@ func init() {
 
 // Skipping definition for base type 'Int16'
 
-// Skipping definition for base type 'Int32'
-
 type Seg uint32
 
 func NewSegId(c *xgb.Conn) (Seg, error) {
@@ -74,9 +74,7 @@ func NewSegId(c *xgb.Conn) (Seg, error) {
 	return Seg(id), nil
 }
 
-// Event definition Completion (0)
-// Size: 32
-
+// Completion is the event number for a CompletionEvent.
 const Completion = 0
 
 type CompletionEvent struct {
@@ -90,7 +88,7 @@ type CompletionEvent struct {
 	Offset uint32
 }
 
-// Event read Completion
+// CompletionEventNew constructs a CompletionEvent value that implements xgb.Event from a byte slice.
 func CompletionEventNew(buf []byte) xgb.Event {
 	v := CompletionEvent{}
 	b := 1 // don't read event number
@@ -120,7 +118,7 @@ func CompletionEventNew(buf []byte) xgb.Event {
 	return v
 }
 
-// Event write Completion
+// Bytes writes a CompletionEvent value to a byte slice.
 func (v CompletionEvent) Bytes() []byte {
 	buf := make([]byte, 32)
 	b := 0
@@ -153,12 +151,14 @@ func (v CompletionEvent) Bytes() []byte {
 	return buf
 }
 
-func (v CompletionEvent) ImplementsEvent() {}
-
+// SequenceId returns the sequence id attached to the Completion event.
+// Events without a sequence number (KeymapNotify) return 0.
+// This is mostly used internally.
 func (v CompletionEvent) SequenceId() uint16 {
 	return v.Sequence
 }
 
+// String is a rudimentary string representation of CompletionEvent.
 func (v CompletionEvent) String() string {
 	fieldVals := make([]string, 0, 7)
 	fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence))
@@ -174,20 +174,20 @@ func init() {
 	xgb.NewExtEventFuncs["MIT-SHM"][0] = CompletionEventNew
 }
 
-// ErrorCopy definition BadSeg (0)
-
+// BadBadSeg is the error number for a BadBadSeg.
 const BadBadSeg = 0
 
 type BadSegError xproto.ValueError
 
+// BadSegErrorNew constructs a BadSegError value that implements xgb.Error from a byte slice.
 func BadSegErrorNew(buf []byte) xgb.Error {
 	v := BadSegError(xproto.ValueErrorNew(buf).(xproto.ValueError))
 	v.NiceName = "BadSeg"
 	return v
 }
 
-func (err BadSegError) ImplementsError() {}
-
+// SequenceId returns the sequence id attached to the BadBadSeg error.
+// This is mostly used internally.
 func (err BadSegError) SequenceId() uint16 {
 	return err.Sequence
 }
@@ -210,29 +210,31 @@ func init() {
 	xgb.NewExtErrorFuncs["MIT-SHM"][0] = BadSegErrorNew
 }
 
-// Request QueryVersion
-// size: 4
+// 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) QueryVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryVersionRequest(c), 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) QueryVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryVersionRequest(c), 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
 	SharedPixmaps bool
 	MajorVersion  uint16
 	MinorVersion  uint16
@@ -242,7 +244,7 @@ type QueryVersionReply struct {
 	// padding: 15 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 {
@@ -254,7 +256,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
@@ -293,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) []byte {
 	size := 4
 	b := 0
@@ -310,30 +313,35 @@ func queryVersionRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request Attach
-// size: 16
+// AttachCookie is a cookie used only for Attach requests.
 type AttachCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Attach
+// Attach sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Attach(c *xgb.Conn, Shmseg Seg, Shmid uint32, ReadOnly bool) AttachCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(attachRequest(c, Shmseg, Shmid, ReadOnly), cookie)
 	return AttachCookie{cookie}
 }
 
+// AttachChecked sends a checked request.
+// If an error occurs, it can be retrieved using AttachCookie.Check()
 func AttachChecked(c *xgb.Conn, Shmseg Seg, Shmid uint32, ReadOnly bool) AttachCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(attachRequest(c, Shmseg, Shmid, ReadOnly), cookie)
 	return AttachCookie{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 AttachCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Attach
+// attachRequest writes a Attach request to a byte slice.
 func attachRequest(c *xgb.Conn, Shmseg Seg, Shmid uint32, ReadOnly bool) []byte {
 	size := 16
 	b := 0
@@ -366,30 +374,35 @@ func attachRequest(c *xgb.Conn, Shmseg Seg, Shmid uint32, ReadOnly bool) []byte
 	return buf
 }
 
-// Request Detach
-// size: 8
+// DetachCookie is a cookie used only for Detach requests.
 type DetachCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Detach
+// Detach sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Detach(c *xgb.Conn, Shmseg Seg) DetachCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(detachRequest(c, Shmseg), cookie)
 	return DetachCookie{cookie}
 }
 
+// DetachChecked sends a checked request.
+// If an error occurs, it can be retrieved using DetachCookie.Check()
 func DetachChecked(c *xgb.Conn, Shmseg Seg) DetachCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(detachRequest(c, Shmseg), cookie)
 	return DetachCookie{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 DetachCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Detach
+// detachRequest writes a Detach request to a byte slice.
 func detachRequest(c *xgb.Conn, Shmseg Seg) []byte {
 	size := 8
 	b := 0
@@ -410,30 +423,35 @@ func detachRequest(c *xgb.Conn, Shmseg Seg) []byte {
 	return buf
 }
 
-// Request PutImage
-// size: 40
+// PutImageCookie is a cookie used only for PutImage requests.
 type PutImageCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for PutImage
+// PutImage sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func PutImage(c *xgb.Conn, Drawable xproto.Drawable, Gc xproto.Gcontext, TotalWidth uint16, TotalHeight uint16, SrcX uint16, SrcY uint16, SrcWidth uint16, SrcHeight uint16, DstX int16, DstY int16, Depth byte, Format byte, SendEvent byte, Shmseg Seg, Offset uint32) PutImageCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(putImageRequest(c, Drawable, Gc, TotalWidth, TotalHeight, SrcX, SrcY, SrcWidth, SrcHeight, DstX, DstY, Depth, Format, SendEvent, Shmseg, Offset), cookie)
 	return PutImageCookie{cookie}
 }
 
+// PutImageChecked sends a checked request.
+// If an error occurs, it can be retrieved using PutImageCookie.Check()
 func PutImageChecked(c *xgb.Conn, Drawable xproto.Drawable, Gc xproto.Gcontext, TotalWidth uint16, TotalHeight uint16, SrcX uint16, SrcY uint16, SrcWidth uint16, SrcHeight uint16, DstX int16, DstY int16, Depth byte, Format byte, SendEvent byte, Shmseg Seg, Offset uint32) PutImageCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(putImageRequest(c, Drawable, Gc, TotalWidth, TotalHeight, SrcX, SrcY, SrcWidth, SrcHeight, DstX, DstY, Depth, Format, SendEvent, Shmseg, Offset), cookie)
 	return PutImageCookie{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 PutImageCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for PutImage
+// putImageRequest writes a PutImage request to a byte slice.
 func putImageRequest(c *xgb.Conn, Drawable xproto.Drawable, Gc xproto.Gcontext, TotalWidth uint16, TotalHeight uint16, SrcX uint16, SrcY uint16, SrcWidth uint16, SrcHeight uint16, DstX int16, DstY int16, Depth byte, Format byte, SendEvent byte, Shmseg Seg, Offset uint32) []byte {
 	size := 40
 	b := 0
@@ -498,35 +516,37 @@ func putImageRequest(c *xgb.Conn, Drawable xproto.Drawable, Gc xproto.Gcontext,
 	return buf
 }
 
-// Request GetImage
-// size: 32
+// GetImageCookie is a cookie used only for GetImage requests.
 type GetImageCookie struct {
 	*xgb.Cookie
 }
 
+// GetImage sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetImageCookie.Reply()
 func GetImage(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, PlaneMask uint32, Format byte, Shmseg Seg, Offset uint32) GetImageCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getImageRequest(c, Drawable, X, Y, Width, Height, PlaneMask, Format, Shmseg, Offset), cookie)
 	return GetImageCookie{cookie}
 }
 
+// GetImageUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetImageUnchecked(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, PlaneMask uint32, Format byte, Shmseg Seg, Offset uint32) GetImageCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getImageRequest(c, Drawable, X, Y, Width, Height, PlaneMask, Format, Shmseg, Offset), cookie)
 	return GetImageCookie{cookie}
 }
 
-// Request reply for GetImage
-// size: 16
+// GetImageReply represents the data returned from a GetImage request.
 type GetImageReply struct {
-	Sequence uint16
-	Length   uint32
+	Sequence uint16 // sequence number of the request for this reply
+	Length   uint32 // number of bytes in this reply
 	Depth    byte
 	Visual   xproto.Visualid
 	Size     uint32
 }
 
-// Waits and reads reply data from request GetImage
+// Reply blocks and returns the reply data for a GetImage request.
 func (cook GetImageCookie) Reply() (*GetImageReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -538,7 +558,7 @@ func (cook GetImageCookie) Reply() (*GetImageReply, error) {
 	return getImageReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetImage
+// getImageReply reads a byte slice into a GetImageReply value.
 func getImageReply(buf []byte) *GetImageReply {
 	v := new(GetImageReply)
 	b := 1 // skip reply determinant
@@ -562,6 +582,7 @@ func getImageReply(buf []byte) *GetImageReply {
 }
 
 // Write request to wire for GetImage
+// getImageRequest writes a GetImage request to a byte slice.
 func getImageRequest(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, PlaneMask uint32, Format byte, Shmseg Seg, Offset uint32) []byte {
 	size := 32
 	b := 0
@@ -608,30 +629,35 @@ func getImageRequest(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Wi
 	return buf
 }
 
-// Request CreatePixmap
-// size: 28
+// CreatePixmapCookie is a cookie used only for CreatePixmap requests.
 type CreatePixmapCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for CreatePixmap
+// CreatePixmap sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CreatePixmap(c *xgb.Conn, Pid xproto.Pixmap, Drawable xproto.Drawable, Width uint16, Height uint16, Depth byte, Shmseg Seg, Offset uint32) CreatePixmapCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(createPixmapRequest(c, Pid, Drawable, Width, Height, Depth, Shmseg, Offset), cookie)
 	return CreatePixmapCookie{cookie}
 }
 
+// CreatePixmapChecked sends a checked request.
+// If an error occurs, it can be retrieved using CreatePixmapCookie.Check()
 func CreatePixmapChecked(c *xgb.Conn, Pid xproto.Pixmap, Drawable xproto.Drawable, Width uint16, Height uint16, Depth byte, Shmseg Seg, Offset uint32) CreatePixmapCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(createPixmapRequest(c, Pid, Drawable, Width, Height, Depth, Shmseg, Offset), cookie)
 	return CreatePixmapCookie{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 CreatePixmapCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for CreatePixmap
+// createPixmapRequest writes a CreatePixmap request to a byte slice.
 func createPixmapRequest(c *xgb.Conn, Pid xproto.Pixmap, Drawable xproto.Drawable, Width uint16, Height uint16, Depth byte, Shmseg Seg, Offset uint32) []byte {
 	size := 28
 	b := 0