Doc fixes and stop exporting ReplyChecked and ReplyUnchecked

2 files changed, 36 insertions, 13 deletions

diff --git a/nexgb/cookie.go b/nexgb/cookie.go
index e75e53c..6b1e4fb 100644
--- a/nexgb/cookie.go
+++ b/nexgb/cookie.go
@@ -22,8 +22,9 @@ type Cookie struct {
 // function for more info on those.)
 // Note that a sequence number is not set until just before the request
 // corresponding to this cookie is sent over the wire.
-// This function should not be used. It is exported for use in the extension
-// sub-packages.
+//
+// Unless you're building requests from bytes by hand, this method should
+// not be used.
 func (c *Conn) NewCookie(checked, reply bool) *Cookie {
 	cookie := &Cookie{
 		conn:      c,
@@ -64,21 +65,25 @@ func (c *Conn) NewCookie(checked, reply bool) *Cookie {
 
 // Reply detects whether this is a checked or unchecked cookie, and calls
 // 'replyChecked' or 'replyUnchecked' appropriately.
-// This should not be used. It is exported for use in extension sub-packages.
+//
+// Unless you're building requests from bytes by hand, this method should
+// not be used.
 func (c Cookie) Reply() ([]byte, error) {
 	// checked
 	if c.errorChan != nil {
-		return c.ReplyChecked()
+		return c.replyChecked()
 	}
-	return c.ReplyUnchecked()
+	return c.replyUnchecked()
 }
 
-// ReplyChecked waits for a response on either the replyChan or errorChan
+// replyChecked waits for a response on either the replyChan or errorChan
 // channels. If the former arrives, the bytes are returned with a nil error.
 // If the latter arrives, no bytes are returned (nil) and the error received
 // is returned.
-// This should not be used. It is exported for use in extension sub-packages.
-func (c Cookie) ReplyChecked() ([]byte, error) {
+//
+// Unless you're building requests from bytes by hand, this method should
+// not be used.
+func (c Cookie) replyChecked() ([]byte, error) {
 	if c.replyChan == nil {
 		return nil, errors.New("Cannot call 'replyChecked' on a cookie that " +
 			"is not expecting a *reply* or an error.")
@@ -97,14 +102,16 @@ func (c Cookie) ReplyChecked() ([]byte, error) {
 	panic("unreachable")
 }
 
-// ReplyChecked waits for a response on either the replyChan or pingChan
+// replyUnchecked waits for a response on either the replyChan or pingChan
 // channels. If the former arrives, the bytes are returned with a nil error.
 // If the latter arrives, no bytes are returned (nil) and a nil error
 // is returned. (In the latter case, the corresponding error can be retrieved
 // from (Wait|Poll)ForEvent asynchronously.)
 // In all honesty, you *probably* don't want to use this method.
-// This should not be used. It is exported for use in extension sub-packages.
-func (c Cookie) ReplyUnchecked() ([]byte, error) {
+//
+// Unless you're building requests from bytes by hand, this method should
+// not be used.
+func (c Cookie) replyUnchecked() ([]byte, error) {
 	if c.replyChan == nil {
 		return nil, errors.New("Cannot call 'replyUnchecked' on a cookie " +
 			"that is not expecting a *reply*.")
@@ -127,7 +134,9 @@ func (c Cookie) ReplyUnchecked() ([]byte, error) {
 // Thus, pingChan is sent a value when the *next* reply is read.
 // If no more replies are being processed, we force a round trip request with
 // GetInputFocus.
-// This should not be used. It is exported for use in extension sub-packages.
+//
+// Unless you're building requests from bytes by hand, this method should
+// not be used.
 func (c Cookie) Check() error {
 	if c.replyChan != nil {
 		return errors.New("Cannot call 'Check' on a cookie that is " +
diff --git a/nexgb/xgb.go b/nexgb/xgb.go
index 7df0fac..c62cc85 100644
--- a/nexgb/xgb.go
+++ b/nexgb/xgb.go
@@ -162,7 +162,7 @@ var NewExtErrorFuncs = make(map[string]map[int]NewErrorFun)
 // error.
 type eventOrError interface{}
 
-// NewID generates a new unused ID for use with requests like CreateWindow.
+// NewId generates a new unused ID for use with requests like CreateWindow.
 // If no new ids can be generated, the id returned is 0 and error is non-nil.
 // This shouldn't be used directly, and is exported for use in the extension
 // sub-packages.
@@ -269,6 +269,20 @@ type request struct {
 // 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, but before it is sent to X.
+//
+// Note that you may safely use NewRequest to send arbitrary byte requests
+// to X. The resulting cookie can be used just like any normal cookie and
+// abides by the same rules, except that for replies, you'll get back the
+// raw byte data. This may be useful for performance critical sections where
+// every allocation counts, since all X requests in XGB allocate a new byte
+// slice. In contrast, NewRequest allocates one small request struct and
+// nothing else. (Except when the cookie buffer is full and has to be flushed.)
+//
+// If you're using NewRequest manually, you'll need to use NewCookie to create
+// a new cookie.
+//
+// In all likelihood, you should be able to copy and paste with some minor
+// edits the generated code for the request you want to issue.
 func (c *Conn) NewRequest(buf []byte, cookie *Cookie) {
 	c.reqChan <- &request{buf: buf, cookie: cookie}
 }