better docs

1 files changed, 66 insertions, 40 deletions

diff --git a/nexgb/screensaver/screensaver.go b/nexgb/screensaver/screensaver.go
index f11113e..0b6ef23 100644
--- a/nexgb/screensaver/screensaver.go
+++ b/nexgb/screensaver/screensaver.go
@@ -2,7 +2,7 @@
 package screensaver
 
 /*
-	This file was generated by screensaver.xml on May 10 2012 8:04:32pm EDT.
+	This file was generated by screensaver.xml on May 10 2012 11:56:19pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -40,6 +40,10 @@ func init() {
 	xgb.NewExtErrorFuncs["MIT-SCREEN-SAVER"] = make(map[int]xgb.NewErrorFun)
 }
 
+// Skipping definition for base type 'Card32'
+
+// Skipping definition for base type 'Double'
+
 // Skipping definition for base type 'Bool'
 
 // Skipping definition for base type 'Float'
@@ -60,10 +64,6 @@ func init() {
 
 // Skipping definition for base type 'Char'
 
-// Skipping definition for base type 'Card32'
-
-// Skipping definition for base type 'Double'
-
 const (
 	KindBlanked  = 0
 	KindInternal = 1
@@ -82,9 +82,7 @@ const (
 	StateDisabled = 3
 )
 
-// Event definition Notify (0)
-// Size: 32
-
+// Notify is the event number for a NotifyEvent.
 const Notify = 0
 
 type NotifyEvent struct {
@@ -101,7 +99,7 @@ type NotifyEvent struct {
 	// padding: 14 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
@@ -144,7 +142,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
@@ -190,12 +188,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, 10)
 	fieldVals = append(fieldVals, xgb.Sprintf("Sequence: %d", v.Sequence))
@@ -214,36 +214,38 @@ func init() {
 	xgb.NewExtEventFuncs["MIT-SCREEN-SAVER"][0] = NotifyEventNew
 }
 
-// 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, ClientMajorVersion byte, ClientMinorVersion byte) 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 byte, ClientMinorVersion byte) 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
 	ServerMajorVersion uint16
 	ServerMinorVersion uint16
 	// padding: 20 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 {
@@ -255,7 +257,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
@@ -280,6 +282,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 byte, ClientMinorVersion byte) []byte {
 	size := 8
 	b := 0
@@ -305,29 +308,31 @@ func queryVersionRequest(c *xgb.Conn, ClientMajorVersion byte, ClientMinorVersio
 	return buf
 }
 
-// Request QueryInfo
-// size: 8
+// QueryInfoCookie is a cookie used only for QueryInfo requests.
 type QueryInfoCookie struct {
 	*xgb.Cookie
 }
 
+// QueryInfo sends a checked request.
+// If an error occurs, it will be returned with the reply by calling QueryInfoCookie.Reply()
 func QueryInfo(c *xgb.Conn, Drawable xproto.Drawable) QueryInfoCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(queryInfoRequest(c, Drawable), cookie)
 	return QueryInfoCookie{cookie}
 }
 
+// QueryInfoUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func QueryInfoUnchecked(c *xgb.Conn, Drawable xproto.Drawable) QueryInfoCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(queryInfoRequest(c, Drawable), cookie)
 	return QueryInfoCookie{cookie}
 }
 
-// Request reply for QueryInfo
-// size: 32
+// QueryInfoReply represents the data returned from a QueryInfo request.
 type QueryInfoReply struct {
-	Sequence         uint16
-	Length           uint32
+	Sequence         uint16 // sequence number of the request for this reply
+	Length           uint32 // number of bytes in this reply
 	State            byte
 	SaverWindow      xproto.Window
 	MsUntilServer    uint32
@@ -337,7 +342,7 @@ type QueryInfoReply struct {
 	// padding: 7 bytes
 }
 
-// Waits and reads reply data from request QueryInfo
+// Reply blocks and returns the reply data for a QueryInfo request.
 func (cook QueryInfoCookie) Reply() (*QueryInfoReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -349,7 +354,7 @@ func (cook QueryInfoCookie) Reply() (*QueryInfoReply, error) {
 	return queryInfoReply(buf), nil
 }
 
-// Read reply into structure from buffer for QueryInfo
+// queryInfoReply reads a byte slice into a QueryInfoReply value.
 func queryInfoReply(buf []byte) *QueryInfoReply {
 	v := new(QueryInfoReply)
 	b := 1 // skip reply determinant
@@ -384,6 +389,7 @@ func queryInfoReply(buf []byte) *QueryInfoReply {
 }
 
 // Write request to wire for QueryInfo
+// queryInfoRequest writes a QueryInfo request to a byte slice.
 func queryInfoRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	size := 8
 	b := 0
@@ -404,30 +410,35 @@ func queryInfoRequest(c *xgb.Conn, Drawable xproto.Drawable) []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, Drawable xproto.Drawable, EventMask uint32) SelectInputCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(selectInputRequest(c, Drawable, EventMask), 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, Drawable xproto.Drawable, EventMask uint32) SelectInputCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(selectInputRequest(c, Drawable, EventMask), 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, Drawable xproto.Drawable, EventMask uint32) []byte {
 	size := 12
 	b := 0
@@ -451,30 +462,35 @@ func selectInputRequest(c *xgb.Conn, Drawable xproto.Drawable, EventMask uint32)
 	return buf
 }
 
-// Request SetAttributes
-// size: xgb.Pad((24 + (4 + xgb.Pad((4 * xgb.PopCount(int(ValueMask)))))))
+// SetAttributesCookie is a cookie used only for SetAttributes requests.
 type SetAttributesCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for SetAttributes
+// SetAttributes sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func SetAttributes(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, BorderWidth uint16, Class byte, Depth byte, Visual xproto.Visualid, ValueMask uint32, ValueList []uint32) SetAttributesCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(setAttributesRequest(c, Drawable, X, Y, Width, Height, BorderWidth, Class, Depth, Visual, ValueMask, ValueList), cookie)
 	return SetAttributesCookie{cookie}
 }
 
+// SetAttributesChecked sends a checked request.
+// If an error occurs, it can be retrieved using SetAttributesCookie.Check()
 func SetAttributesChecked(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, BorderWidth uint16, Class byte, Depth byte, Visual xproto.Visualid, ValueMask uint32, ValueList []uint32) SetAttributesCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(setAttributesRequest(c, Drawable, X, Y, Width, Height, BorderWidth, Class, Depth, Visual, ValueMask, ValueList), cookie)
 	return SetAttributesCookie{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 SetAttributesCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for SetAttributes
+// setAttributesRequest writes a SetAttributes request to a byte slice.
 func setAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int16, Width uint16, Height uint16, BorderWidth uint16, Class byte, Depth byte, Visual xproto.Visualid, ValueMask uint32, ValueList []uint32) []byte {
 	size := xgb.Pad((24 + (4 + xgb.Pad((4 * xgb.PopCount(int(ValueMask)))))))
 	b := 0
@@ -527,30 +543,35 @@ func setAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable, X int16, Y int1
 	return buf
 }
 
-// Request UnsetAttributes
-// size: 8
+// UnsetAttributesCookie is a cookie used only for UnsetAttributes requests.
 type UnsetAttributesCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for UnsetAttributes
+// UnsetAttributes sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func UnsetAttributes(c *xgb.Conn, Drawable xproto.Drawable) UnsetAttributesCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(unsetAttributesRequest(c, Drawable), cookie)
 	return UnsetAttributesCookie{cookie}
 }
 
+// UnsetAttributesChecked sends a checked request.
+// If an error occurs, it can be retrieved using UnsetAttributesCookie.Check()
 func UnsetAttributesChecked(c *xgb.Conn, Drawable xproto.Drawable) UnsetAttributesCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(unsetAttributesRequest(c, Drawable), cookie)
 	return UnsetAttributesCookie{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 UnsetAttributesCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for UnsetAttributes
+// unsetAttributesRequest writes a UnsetAttributes request to a byte slice.
 func unsetAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	size := 8
 	b := 0
@@ -571,30 +592,35 @@ func unsetAttributesRequest(c *xgb.Conn, Drawable xproto.Drawable) []byte {
 	return buf
 }
 
-// Request Suspend
-// size: 8
+// SuspendCookie is a cookie used only for Suspend requests.
 type SuspendCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Suspend
+// Suspend sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Suspend(c *xgb.Conn, Suspend bool) SuspendCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(suspendRequest(c, Suspend), cookie)
 	return SuspendCookie{cookie}
 }
 
+// SuspendChecked sends a checked request.
+// If an error occurs, it can be retrieved using SuspendCookie.Check()
 func SuspendChecked(c *xgb.Conn, Suspend bool) SuspendCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(suspendRequest(c, Suspend), cookie)
 	return SuspendCookie{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 SuspendCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Suspend
+// suspendRequest writes a Suspend request to a byte slice.
 func suspendRequest(c *xgb.Conn, Suspend bool) []byte {
 	size := 8
 	b := 0