From c00652934e4ec68016a152b9bea10273b0be8726 Mon Sep 17 00:00:00 2001
From: "Andrew Gallant (Ocelot)" <Andrew.Gallant@tufts.edu>
Date: Thu, 10 May 2012 23:57:34 -0400
Subject: better docs
---
nexgb/damage/damage.go | 89 +++++++++++++++++++++++++++++++-------------------
1 file changed, 55 insertions(+), 34 deletions(-)
(limited to 'nexgb/damage')
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
--
cgit v1.2.3-70-g09d2