From 58bb2572c5d1e88689aa1b30dc55b702acf57f4f Mon Sep 17 00:00:00 2001 From: "Andrew Gallant (Ocelot)" Date: Sat, 26 May 2012 18:22:25 -0400 Subject: Doc touchups. --- nexgb/cookie.go | 2 +- nexgb/doc.go | 14 +++++++------- nexgb/xgb.go | 23 ++++++++++++++--------- 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/nexgb/cookie.go b/nexgb/cookie.go index 0f32990..e75e53c 100644 --- a/nexgb/cookie.go +++ b/nexgb/cookie.go @@ -16,7 +16,7 @@ type Cookie struct { pingChan chan bool } -// newCookie creates a new cookie with the correct channels initialized +// NewCookie creates a new cookie with the correct channels initialized // depending upon the values of 'checked' and 'reply'. Together, there are // four different kinds of cookies. (See more detailed comments in the // function for more info on those.) diff --git a/nexgb/doc.go b/nexgb/doc.go index 9a9531c..a5bb6fe 100644 --- a/nexgb/doc.go +++ b/nexgb/doc.go @@ -107,16 +107,16 @@ can be found in examples/xinerama. Parallelism XGB can benefit greatly from parallelism due to its concurrent design. For -evidence of this claim, please see the benchmarks in xgb_test.go. +evidence of this claim, please see the benchmarks in xproto/xproto_test.go. Tests -xgb_test.go contains a number of contrived tests that stress particular corners -of XGB that I presume could be problem areas. Namely: requests with no replies, -requests with replies, checked errors, unchecked errors, sequence number -wrapping, cookie buffer flushing (i.e., forcing a round trip every N requests -made that don't have a reply), getting/setting properties and creating a window -and listening to StructureNotify events. +xproto/xproto_test.go contains a number of contrived tests that stress +particular corners of XGB that I presume could be problem areas. Namely: +requests with no replies, requests with replies, checked errors, unchecked +errors, sequence number wrapping, cookie buffer flushing (i.e., forcing a round +trip every N requests made that don't have a reply), getting/setting properties +and creating a window and listening to StructureNotify events. Code Generator diff --git a/nexgb/xgb.go b/nexgb/xgb.go index b0a7307..7df0fac 100644 --- a/nexgb/xgb.go +++ b/nexgb/xgb.go @@ -78,10 +78,10 @@ func NewConn() (*Conn, error) { // If 'display' is empty it will be taken from os.Getenv("DISPLAY"). // // Examples: -// NewConn(":1") -> net.Dial("unix", "", "/tmp/.X11-unix/X1") -// NewConn("/tmp/launch-123/:0") -> net.Dial("unix", "", "/tmp/launch-123/:0") -// NewConn("hostname:2.1") -> net.Dial("tcp", "", "hostname:6002") -// NewConn("tcp/hostname:1.0") -> net.Dial("tcp", "", "hostname:6001") +// NewConn(":1") -> net.Dial("unix", "", "/tmp/.X11-unix/X1") +// NewConn("/tmp/launch-12/:0") -> net.Dial("unix", "", "/tmp/launch-12/:0") +// NewConn("hostname:2.1") -> net.Dial("tcp", "", "hostname:6002") +// NewConn("tcp/hostname:1.0") -> net.Dial("tcp", "", "hostname:6001") func NewConnDisplay(display string) (*Conn, error) { conn := &Conn{} @@ -265,10 +265,10 @@ type request struct { cookie *Cookie } -// NewRequest takes the bytes an a cookie, constructs a request type, -// and sends it over the Conn.reqChan channel. +// NewRequest takes the bytes and a cookie of a particular request, constructs +// a request type, and sends it over the Conn.reqChan channel. // Note that the sequence number is added to the cookie after it is sent -// over the request channel. +// over the request channel, but before it is sent to X. func (c *Conn) NewRequest(buf []byte, cookie *Cookie) { c.reqChan <- &request{buf: buf, cookie: cookie} } @@ -476,13 +476,18 @@ func processEventOrError(everr eventOrError) (Event, Error) { // WaitForEvent returns the next event from the server. // It will block until an event is available. +// WaitForEvent returns either an Event or an Error. (Returning neither or both +// is a bug.) Note than an Error here is an X error and not an XGB error. That +// is, X errors are sometimes completely expected (and you may want to ignore +// them in some cases). func (c *Conn) WaitForEvent() (Event, Error) { return processEventOrError(<-c.eventChan) } // PollForEvent returns the next event from the server if one is available in -// the internal queue. -// It will not block. +// the internal queue without blocking. Note that unlike WaitForEvent, both +// Event and Error could be nil. Indeed, they are both nil when the event queue +// is empty. func (c *Conn) PollForEvent() (Event, Error) { select { case everr := <-c.eventChan: -- cgit v1.2.3-70-g09d2