better docs

1 files changed, 85 insertions, 53 deletions

diff --git a/nexgb/dpms/dpms.go b/nexgb/dpms/dpms.go
index de748e4..e3e095a 100644
--- a/nexgb/dpms/dpms.go
+++ b/nexgb/dpms/dpms.go
@@ -2,7 +2,7 @@
 package dpms
 
 /*
-	This file was generated by dpms.xml on May 10 2012 8:04:31pm EDT.
+	This file was generated by dpms.xml on May 10 2012 11:56:18pm EDT.
 	This file is automatically generated. Edit at your peril!
 */
 
@@ -40,6 +40,14 @@ func init() {
 	xgb.NewExtErrorFuncs["DPMS"] = make(map[int]xgb.NewErrorFun)
 }
 
+// Skipping definition for base type 'Card8'
+
+// Skipping definition for base type 'Int16'
+
+// Skipping definition for base type 'Int32'
+
+// Skipping definition for base type 'Void'
+
 // Skipping definition for base type 'Byte'
 
 // Skipping definition for base type 'Int8'
@@ -56,14 +64,6 @@ func init() {
 
 // Skipping definition for base type 'Float'
 
-// Skipping definition for base type 'Card8'
-
-// Skipping definition for base type 'Int16'
-
-// Skipping definition for base type 'Int32'
-
-// Skipping definition for base type 'Void'
-
 const (
 	DPMSModeOn      = 0
 	DPMSModeStandby = 1
@@ -71,35 +71,37 @@ const (
 	DPMSModeOff     = 3
 )
 
-// Request GetVersion
-// size: 8
+// GetVersionCookie is a cookie used only for GetVersion requests.
 type GetVersionCookie struct {
 	*xgb.Cookie
 }
 
+// GetVersion sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetVersionCookie.Reply()
 func GetVersion(c *xgb.Conn, ClientMajorVersion uint16, ClientMinorVersion uint16) GetVersionCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getVersionRequest(c, ClientMajorVersion, ClientMinorVersion), cookie)
 	return GetVersionCookie{cookie}
 }
 
+// GetVersionUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetVersionUnchecked(c *xgb.Conn, ClientMajorVersion uint16, ClientMinorVersion uint16) GetVersionCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getVersionRequest(c, ClientMajorVersion, ClientMinorVersion), cookie)
 	return GetVersionCookie{cookie}
 }
 
-// Request reply for GetVersion
-// size: 12
+// GetVersionReply represents the data returned from a GetVersion request.
 type GetVersionReply 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
 }
 
-// Waits and reads reply data from request GetVersion
+// Reply blocks and returns the reply data for a GetVersion request.
 func (cook GetVersionCookie) Reply() (*GetVersionReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -111,7 +113,7 @@ func (cook GetVersionCookie) Reply() (*GetVersionReply, error) {
 	return getVersionReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetVersion
+// getVersionReply reads a byte slice into a GetVersionReply value.
 func getVersionReply(buf []byte) *GetVersionReply {
 	v := new(GetVersionReply)
 	b := 1 // skip reply determinant
@@ -134,6 +136,7 @@ func getVersionReply(buf []byte) *GetVersionReply {
 }
 
 // Write request to wire for GetVersion
+// getVersionRequest writes a GetVersion request to a byte slice.
 func getVersionRequest(c *xgb.Conn, ClientMajorVersion uint16, ClientMinorVersion uint16) []byte {
 	size := 8
 	b := 0
@@ -157,35 +160,37 @@ func getVersionRequest(c *xgb.Conn, ClientMajorVersion uint16, ClientMinorVersio
 	return buf
 }
 
-// Request Capable
-// size: 4
+// CapableCookie is a cookie used only for Capable requests.
 type CapableCookie struct {
 	*xgb.Cookie
 }
 
+// Capable sends a checked request.
+// If an error occurs, it will be returned with the reply by calling CapableCookie.Reply()
 func Capable(c *xgb.Conn) CapableCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(capableRequest(c), cookie)
 	return CapableCookie{cookie}
 }
 
+// CapableUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func CapableUnchecked(c *xgb.Conn) CapableCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(capableRequest(c), cookie)
 	return CapableCookie{cookie}
 }
 
-// Request reply for Capable
-// size: 32
+// CapableReply represents the data returned from a Capable request.
 type CapableReply 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
 	Capable bool
 	// padding: 23 bytes
 }
 
-// Waits and reads reply data from request Capable
+// Reply blocks and returns the reply data for a Capable request.
 func (cook CapableCookie) Reply() (*CapableReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -197,7 +202,7 @@ func (cook CapableCookie) Reply() (*CapableReply, error) {
 	return capableReply(buf), nil
 }
 
-// Read reply into structure from buffer for Capable
+// capableReply reads a byte slice into a CapableReply value.
 func capableReply(buf []byte) *CapableReply {
 	v := new(CapableReply)
 	b := 1 // skip reply determinant
@@ -223,6 +228,7 @@ func capableReply(buf []byte) *CapableReply {
 }
 
 // Write request to wire for Capable
+// capableRequest writes a Capable request to a byte slice.
 func capableRequest(c *xgb.Conn) []byte {
 	size := 4
 	b := 0
@@ -240,29 +246,31 @@ func capableRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request GetTimeouts
-// size: 4
+// GetTimeoutsCookie is a cookie used only for GetTimeouts requests.
 type GetTimeoutsCookie struct {
 	*xgb.Cookie
 }
 
+// GetTimeouts sends a checked request.
+// If an error occurs, it will be returned with the reply by calling GetTimeoutsCookie.Reply()
 func GetTimeouts(c *xgb.Conn) GetTimeoutsCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(getTimeoutsRequest(c), cookie)
 	return GetTimeoutsCookie{cookie}
 }
 
+// GetTimeoutsUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func GetTimeoutsUnchecked(c *xgb.Conn) GetTimeoutsCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(getTimeoutsRequest(c), cookie)
 	return GetTimeoutsCookie{cookie}
 }
 
-// Request reply for GetTimeouts
-// size: 32
+// GetTimeoutsReply represents the data returned from a GetTimeouts request.
 type GetTimeoutsReply 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
 	StandbyTimeout uint16
 	SuspendTimeout uint16
@@ -270,7 +278,7 @@ type GetTimeoutsReply struct {
 	// padding: 18 bytes
 }
 
-// Waits and reads reply data from request GetTimeouts
+// Reply blocks and returns the reply data for a GetTimeouts request.
 func (cook GetTimeoutsCookie) Reply() (*GetTimeoutsReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -282,7 +290,7 @@ func (cook GetTimeoutsCookie) Reply() (*GetTimeoutsReply, error) {
 	return getTimeoutsReply(buf), nil
 }
 
-// Read reply into structure from buffer for GetTimeouts
+// getTimeoutsReply reads a byte slice into a GetTimeoutsReply value.
 func getTimeoutsReply(buf []byte) *GetTimeoutsReply {
 	v := new(GetTimeoutsReply)
 	b := 1 // skip reply determinant
@@ -310,6 +318,7 @@ func getTimeoutsReply(buf []byte) *GetTimeoutsReply {
 }
 
 // Write request to wire for GetTimeouts
+// getTimeoutsRequest writes a GetTimeouts request to a byte slice.
 func getTimeoutsRequest(c *xgb.Conn) []byte {
 	size := 4
 	b := 0
@@ -327,30 +336,35 @@ func getTimeoutsRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request SetTimeouts
-// size: 12
+// SetTimeoutsCookie is a cookie used only for SetTimeouts requests.
 type SetTimeoutsCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for SetTimeouts
+// SetTimeouts sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func SetTimeouts(c *xgb.Conn, StandbyTimeout uint16, SuspendTimeout uint16, OffTimeout uint16) SetTimeoutsCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(setTimeoutsRequest(c, StandbyTimeout, SuspendTimeout, OffTimeout), cookie)
 	return SetTimeoutsCookie{cookie}
 }
 
+// SetTimeoutsChecked sends a checked request.
+// If an error occurs, it can be retrieved using SetTimeoutsCookie.Check()
 func SetTimeoutsChecked(c *xgb.Conn, StandbyTimeout uint16, SuspendTimeout uint16, OffTimeout uint16) SetTimeoutsCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(setTimeoutsRequest(c, StandbyTimeout, SuspendTimeout, OffTimeout), cookie)
 	return SetTimeoutsCookie{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 SetTimeoutsCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for SetTimeouts
+// setTimeoutsRequest writes a SetTimeouts request to a byte slice.
 func setTimeoutsRequest(c *xgb.Conn, StandbyTimeout uint16, SuspendTimeout uint16, OffTimeout uint16) []byte {
 	size := 12
 	b := 0
@@ -377,30 +391,35 @@ func setTimeoutsRequest(c *xgb.Conn, StandbyTimeout uint16, SuspendTimeout uint1
 	return buf
 }
 
-// Request Enable
-// size: 4
+// EnableCookie is a cookie used only for Enable requests.
 type EnableCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Enable
+// Enable sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Enable(c *xgb.Conn) EnableCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(enableRequest(c), cookie)
 	return EnableCookie{cookie}
 }
 
+// EnableChecked sends a checked request.
+// If an error occurs, it can be retrieved using EnableCookie.Check()
 func EnableChecked(c *xgb.Conn) EnableCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(enableRequest(c), cookie)
 	return EnableCookie{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 EnableCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // 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
@@ -418,30 +437,35 @@ func enableRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request Disable
-// size: 4
+// DisableCookie is a cookie used only for Disable requests.
 type DisableCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for Disable
+// Disable sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func Disable(c *xgb.Conn) DisableCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(disableRequest(c), cookie)
 	return DisableCookie{cookie}
 }
 
+// DisableChecked sends a checked request.
+// If an error occurs, it can be retrieved using DisableCookie.Check()
 func DisableChecked(c *xgb.Conn) DisableCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(disableRequest(c), cookie)
 	return DisableCookie{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 DisableCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for Disable
+// disableRequest writes a Disable request to a byte slice.
 func disableRequest(c *xgb.Conn) []byte {
 	size := 4
 	b := 0
@@ -459,30 +483,35 @@ func disableRequest(c *xgb.Conn) []byte {
 	return buf
 }
 
-// Request ForceLevel
-// size: 8
+// ForceLevelCookie is a cookie used only for ForceLevel requests.
 type ForceLevelCookie struct {
 	*xgb.Cookie
 }
 
-// Write request to wire for ForceLevel
+// ForceLevel sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func ForceLevel(c *xgb.Conn, PowerLevel uint16) ForceLevelCookie {
 	cookie := c.NewCookie(false, false)
 	c.NewRequest(forceLevelRequest(c, PowerLevel), cookie)
 	return ForceLevelCookie{cookie}
 }
 
+// ForceLevelChecked sends a checked request.
+// If an error occurs, it can be retrieved using ForceLevelCookie.Check()
 func ForceLevelChecked(c *xgb.Conn, PowerLevel uint16) ForceLevelCookie {
 	cookie := c.NewCookie(true, false)
 	c.NewRequest(forceLevelRequest(c, PowerLevel), cookie)
 	return ForceLevelCookie{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 ForceLevelCookie) Check() error {
 	return cook.Cookie.Check()
 }
 
 // Write request to wire for ForceLevel
+// forceLevelRequest writes a ForceLevel request to a byte slice.
 func forceLevelRequest(c *xgb.Conn, PowerLevel uint16) []byte {
 	size := 8
 	b := 0
@@ -503,36 +532,38 @@ func forceLevelRequest(c *xgb.Conn, PowerLevel uint16) []byte {
 	return buf
 }
 
-// Request Info
-// size: 4
+// InfoCookie is a cookie used only for Info requests.
 type InfoCookie struct {
 	*xgb.Cookie
 }
 
+// Info sends a checked request.
+// If an error occurs, it will be returned with the reply by calling InfoCookie.Reply()
 func Info(c *xgb.Conn) InfoCookie {
 	cookie := c.NewCookie(true, true)
 	c.NewRequest(infoRequest(c), cookie)
 	return InfoCookie{cookie}
 }
 
+// InfoUnchecked sends an unchecked request.
+// If an error occurs, it can only be retrieved using xgb.WaitForEvent or xgb.PollForEvent.
 func InfoUnchecked(c *xgb.Conn) InfoCookie {
 	cookie := c.NewCookie(false, true)
 	c.NewRequest(infoRequest(c), cookie)
 	return InfoCookie{cookie}
 }
 
-// Request reply for Info
-// size: 32
+// InfoReply represents the data returned from a Info request.
 type InfoReply 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
 	PowerLevel uint16
 	State      bool
 	// padding: 21 bytes
 }
 
-// Waits and reads reply data from request Info
+// Reply blocks and returns the reply data for a Info request.
 func (cook InfoCookie) Reply() (*InfoReply, error) {
 	buf, err := cook.Cookie.Reply()
 	if err != nil {
@@ -544,7 +575,7 @@ func (cook InfoCookie) Reply() (*InfoReply, error) {
 	return infoReply(buf), nil
 }
 
-// Read reply into structure from buffer for Info
+// infoReply reads a byte slice into a InfoReply value.
 func infoReply(buf []byte) *InfoReply {
 	v := new(InfoReply)
 	b := 1 // skip reply determinant
@@ -573,6 +604,7 @@ func infoReply(buf []byte) *InfoReply {
 }
 
 // Write request to wire for Info
+// infoRequest writes a Info request to a byte slice.
 func infoRequest(c *xgb.Conn) []byte {
 	size := 4
 	b := 0