better docs

1 files changed, 92 insertions, 55 deletions

diff --git a/nexgb/shape/shape.go b/nexgb/shape/shape.go
index 97be0f7..664c5f4 100644
--- a/nexgb/shape/shape.go
+++ b/nexgb/shape/shape.go
@@ -2,7 +2,7 @@
 package shape
 
 /*
-	This file was generated by shape.xml on May 10 2012 8:04:32pm EDT.
+	This file was generated by shape.xml on May 10 2012 11:56:19pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -82,9 +82,7 @@ type Op byte
 
 type Kind byte
 
-// Event definition Notify (0)
-// Size: 32
-
+// Notify is the event number for a NotifyEvent.
 const Notify = 0
 
 type NotifyEvent struct {
@@ -100,7 +98,7 @@ type NotifyEvent struct {
 	// padding: 11 bytes
 }
 
-// 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
@@ -141,7 +139,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
@@ -185,12 +183,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, 9)
 	fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence))
@@ -209,35 +209,37 @@ func init() {
 	xgb.NewExtEventFuncs["SHAPE"][0] = NotifyEventNew
 }
 
-// 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: 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 {
@@ -249,7 +251,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
@@ -272,6 +274,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
@@ -289,30 +292,35 @@ func queryVersionRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request Rectangles
-// size: xgb.Pad((16 + xgb.Pad((len(Rectangles) * 8))))
+// RectanglesCookie is a cookie used only for Rectangles requests.
 type RectanglesCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Rectangles
+// Rectangles sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Rectangles(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering byte, DestinationWindow xproto.Window, XOffset int16, YOffset int16, Rectangles []xproto.Rectangle) RectanglesCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(rectanglesRequest(c, Operation, DestinationKind, Ordering, DestinationWindow, XOffset, YOffset, Rectangles), cookie)
 	return RectanglesCookie{cookie}
 }
 
+// RectanglesChecked sends a checked request.
+// If an error occurs, it can be retrieved using RectanglesCookie.Check()
 func RectanglesChecked(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering byte, DestinationWindow xproto.Window, XOffset int16, YOffset int16, Rectangles []xproto.Rectangle) RectanglesCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(rectanglesRequest(c, Operation, DestinationKind, Ordering, DestinationWindow, XOffset, YOffset, Rectangles), cookie)
 	return RectanglesCookie{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 RectanglesCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Rectangles
+// rectanglesRequest writes a Rectangles request to a byte slice.
 func rectanglesRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering byte, DestinationWindow xproto.Window, XOffset int16, YOffset int16, Rectangles []xproto.Rectangle) []byte {
 	size := xgb.Pad((16 + xgb.Pad((len(Rectangles) * 8))))
 	b := 0
@@ -352,30 +360,35 @@ func rectanglesRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, Ordering
 	return buf
 }
 
-// Request Mask
-// size: 20
+// MaskCookie is a cookie used only for Mask requests.
 type MaskCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Mask
+// Mask sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Mask(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceBitmap xproto.Pixmap) MaskCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(maskRequest(c, Operation, DestinationKind, DestinationWindow, XOffset, YOffset, SourceBitmap), cookie)
 	return MaskCookie{cookie}
 }
 
+// MaskChecked sends a checked request.
+// If an error occurs, it can be retrieved using MaskCookie.Check()
 func MaskChecked(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceBitmap xproto.Pixmap) MaskCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(maskRequest(c, Operation, DestinationKind, DestinationWindow, XOffset, YOffset, SourceBitmap), cookie)
 	return MaskCookie{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 MaskCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Mask
+// maskRequest writes a Mask request to a byte slice.
 func maskRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceBitmap xproto.Pixmap) []byte {
 	size := 20
 	b := 0
@@ -413,30 +426,35 @@ func maskRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, DestinationWin
 	return buf
 }
 
-// Request Combine
-// size: 20
+// CombineCookie is a cookie used only for Combine requests.
 type CombineCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Combine
+// Combine sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Combine(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceWindow xproto.Window) CombineCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(combineRequest(c, Operation, DestinationKind, SourceKind, DestinationWindow, XOffset, YOffset, SourceWindow), cookie)
 	return CombineCookie{cookie}
 }
 
+// CombineChecked sends a checked request.
+// If an error occurs, it can be retrieved using CombineCookie.Check()
 func CombineChecked(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceWindow xproto.Window) CombineCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(combineRequest(c, Operation, DestinationKind, SourceKind, DestinationWindow, XOffset, YOffset, SourceWindow), cookie)
 	return CombineCookie{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 CombineCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Combine
+// combineRequest writes a Combine request to a byte slice.
 func combineRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16, SourceWindow xproto.Window) []byte {
 	size := 20
 	b := 0
@@ -477,30 +495,35 @@ func combineRequest(c *xgb.Conn, Operation Op, DestinationKind Kind, SourceKind
 	return buf
 }
 
-// Request Offset
-// size: 16
+// OffsetCookie is a cookie used only for Offset requests.
 type OffsetCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Offset
+// Offset sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Offset(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16) OffsetCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(offsetRequest(c, DestinationKind, DestinationWindow, XOffset, YOffset), cookie)
 	return OffsetCookie{cookie}
 }
 
+// OffsetChecked sends a checked request.
+// If an error occurs, it can be retrieved using OffsetCookie.Check()
 func OffsetChecked(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16) OffsetCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(offsetRequest(c, DestinationKind, DestinationWindow, XOffset, YOffset), cookie)
 	return OffsetCookie{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 OffsetCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Offset
+// offsetRequest writes a Offset request to a byte slice.
 func offsetRequest(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.Window, XOffset int16, YOffset int16) []byte {
 	size := 16
 	b := 0
@@ -532,29 +555,31 @@ func offsetRequest(c *xgb.Conn, DestinationKind Kind, DestinationWindow xproto.W
 	return buf
 }
 
-// Request QueryExtents
-// size: 8
+// QueryExtentsCookie is a cookie used only for QueryExtents requests.
 type QueryExtentsCookie struct {
 	*xgb.Cookie
 }
 
+// QueryExtents sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryExtentsCookie.Reply()
 func QueryExtents(c *xgb.Conn, DestinationWindow xproto.Window) QueryExtentsCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryExtentsRequest(c, DestinationWindow), cookie)
 	return QueryExtentsCookie{cookie}
 }
 
+// QueryExtentsUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryExtentsUnchecked(c *xgb.Conn, DestinationWindow xproto.Window) QueryExtentsCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryExtentsRequest(c, DestinationWindow), cookie)
 	return QueryExtentsCookie{cookie}
 }
 
-// Request reply for QueryExtents
-// size: 28
+// QueryExtentsReply represents the data returned from a QueryExtents request.
 type QueryExtentsReply 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
 	BoundingShaped bool
 	ClipShaped     bool
@@ -569,7 +594,7 @@ type QueryExtentsReply struct {
 	ClipShapeExtentsHeight     uint16
 }
 
-// Waits and reads reply data from request QueryExtents
+// Reply blocks and returns the reply data for a QueryExtents request.
 func (cook QueryExtentsCookie) Reply() (*QueryExtentsReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -581,7 +606,7 @@ func (cook QueryExtentsCookie) Reply() (*QueryExtentsReply, error) {
 	return queryExtentsReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryExtents
+// queryExtentsReply reads a byte slice into a QueryExtentsReply value.
 func queryExtentsReply(buf []byte) *QueryExtentsReply {
 	v := new(QueryExtentsReply)
 	b := 1 // skip reply determinant
@@ -638,6 +663,7 @@ func queryExtentsReply(buf []byte) *QueryExtentsReply {
 }
 
 // Write request to wire for QueryExtents
+// queryExtentsRequest writes a QueryExtents request to a byte slice.
 func queryExtentsRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte {
 	size := 8
 	b := 0
@@ -658,30 +684,35 @@ func queryExtentsRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte {
 	return buf
 }
 
-// Request SelectInput
-// size: 12
+// SelectInputCookie is a cookie used only for SelectInput requests.
 type SelectInputCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for SelectInput
+// SelectInput sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func SelectInput(c *xgb.Conn, DestinationWindow xproto.Window, Enable bool) SelectInputCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(selectInputRequest(c, DestinationWindow, Enable), cookie)
 	return SelectInputCookie{cookie}
 }
 
+// SelectInputChecked sends a checked request.
+// If an error occurs, it can be retrieved using SelectInputCookie.Check()
 func SelectInputChecked(c *xgb.Conn, DestinationWindow xproto.Window, Enable bool) SelectInputCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(selectInputRequest(c, DestinationWindow, Enable), cookie)
 	return SelectInputCookie{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 SelectInputCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for SelectInput
+// selectInputRequest writes a SelectInput request to a byte slice.
 func selectInputRequest(c *xgb.Conn, DestinationWindow xproto.Window, Enable bool) []byte {
 	size := 12
 	b := 0
@@ -711,33 +742,35 @@ func selectInputRequest(c *xgb.Conn, DestinationWindow xproto.Window, Enable boo
 	return buf
 }
 
-// Request InputSelected
-// size: 8
+// InputSelectedCookie is a cookie used only for InputSelected requests.
 type InputSelectedCookie struct {
 	*xgb.Cookie
 }
 
+// InputSelected sends a checked request.
+// If an error occurs, it will be returned with the reply by calling InputSelectedCookie.Reply()
 func InputSelected(c *xgb.Conn, DestinationWindow xproto.Window) InputSelectedCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(inputSelectedRequest(c, DestinationWindow), cookie)
 	return InputSelectedCookie{cookie}
 }
 
+// InputSelectedUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func InputSelectedUnchecked(c *xgb.Conn, DestinationWindow xproto.Window) InputSelectedCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(inputSelectedRequest(c, DestinationWindow), cookie)
 	return InputSelectedCookie{cookie}
 }
 
-// Request reply for InputSelected
-// size: 8
+// InputSelectedReply represents the data returned from a InputSelected request.
 type InputSelectedReply 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
 }
 
-// Waits and reads reply data from request InputSelected
+// Reply blocks and returns the reply data for a InputSelected request.
 func (cook InputSelectedCookie) Reply() (*InputSelectedReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -749,7 +782,7 @@ func (cook InputSelectedCookie) Reply() (*InputSelectedReply, error) {
 	return inputSelectedReply(buf), nil
 }
 
-// Read reply into structure from buffer for InputSelected
+// inputSelectedReply reads a byte slice into a InputSelectedReply value.
 func inputSelectedReply(buf []byte) *InputSelectedReply {
 	v := new(InputSelectedReply)
 	b := 1 // skip reply determinant
@@ -771,6 +804,7 @@ func inputSelectedReply(buf []byte) *InputSelectedReply {
 }
 
 // Write request to wire for InputSelected
+// inputSelectedRequest writes a InputSelected request to a byte slice.
 func inputSelectedRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte {
 	size := 8
 	b := 0
@@ -791,36 +825,38 @@ func inputSelectedRequest(c *xgb.Conn, DestinationWindow xproto.Window) []byte {
 	return buf
 }
 
-// Request GetRectangles
-// size: 12
+// GetRectanglesCookie is a cookie used only for GetRectangles requests.
 type GetRectanglesCookie struct {
 	*xgb.Cookie
 }
 
+// GetRectangles sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetRectanglesCookie.Reply()
 func GetRectangles(c *xgb.Conn, Window xproto.Window, SourceKind Kind) GetRectanglesCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getRectanglesRequest(c, Window, SourceKind), cookie)
 	return GetRectanglesCookie{cookie}
 }
 
+// GetRectanglesUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetRectanglesUnchecked(c *xgb.Conn, Window xproto.Window, SourceKind Kind) GetRectanglesCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getRectanglesRequest(c, Window, SourceKind), cookie)
 	return GetRectanglesCookie{cookie}
 }
 
-// Request reply for GetRectangles
-// size: (32 + xgb.Pad((int(RectanglesLen) * 8)))
+// GetRectanglesReply represents the data returned from a GetRectangles request.
 type GetRectanglesReply struct {
-	Sequence      uint16
-	Length        uint32
+	Sequence      uint16 // sequence number of the request for this reply
+	Length        uint32 // number of bytes in this reply
 	Ordering      byte
 	RectanglesLen uint32
 	// padding: 20 bytes
 	Rectangles []xproto.Rectangle // size: xgb.Pad((int(RectanglesLen) * 8))
 }
 
-// Waits and reads reply data from request GetRectangles
+// Reply blocks and returns the reply data for a GetRectangles request.
 func (cook GetRectanglesCookie) Reply() (*GetRectanglesReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -832,7 +868,7 @@ func (cook GetRectanglesCookie) Reply() (*GetRectanglesReply, error) {
 	return getRectanglesReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetRectangles
+// getRectanglesReply reads a byte slice into a GetRectanglesReply value.
 func getRectanglesReply(buf []byte) *GetRectanglesReply {
 	v := new(GetRectanglesReply)
 	b := 1 // skip reply determinant
@@ -858,6 +894,7 @@ func getRectanglesReply(buf []byte) *GetRectanglesReply {
 }
 
 // Write request to wire for GetRectangles
+// getRectanglesRequest writes a GetRectangles request to a byte slice.
 func getRectanglesRequest(c *xgb.Conn, Window xproto.Window, SourceKind Kind) []byte {
 	size := 12
 	b := 0