better docs

5 files changed, 80 insertions, 45 deletions

diff --git a/nexgb/xgbgen/go_error.go b/nexgb/xgbgen/go_error.go
index b7721be..81a017b 100644
--- a/nexgb/xgbgen/go_error.go
+++ b/nexgb/xgbgen/go_error.go
@@ -6,9 +6,7 @@ import (
 
 // Error types
 func (e *Error) Define(c *Context) {
-	c.Putln("// Error definition %s (%d)", e.SrcName(), e.Number)
-	c.Putln("// Size: %s", e.Size())
-	c.Putln("")
+	c.Putln("// %s is the error number for a %s.", e.ErrConst(), e.ErrConst())
 	c.Putln("const %s = %d", e.ErrConst(), e.Number)
 	c.Putln("")
 	c.Putln("type %s struct {", e.ErrType())
@@ -40,7 +38,8 @@ func (e *Error) Define(c *Context) {
 }
 
 func (e *Error) Read(c *Context) {
-	c.Putln("// Error read %s", e.SrcName())
+	c.Putln("// %sNew constructs a %s value that implements xgb.Error from "+
+		"a byte slice.", e.ErrType(), e.ErrType())
 	c.Putln("func %sNew(buf []byte) xgb.Error {", e.ErrType())
 	c.Putln("v := %s{}", e.ErrType())
 	c.Putln("v.NiceName = \"%s\"", e.SrcName())
@@ -62,8 +61,9 @@ func (e *Error) Read(c *Context) {
 
 // ImplementsError writes functions to implement the XGB Error interface.
 func (e *Error) ImplementsError(c *Context) {
-	c.Putln("func (err %s) ImplementsError() { }", e.ErrType())
-	c.Putln("")
+	c.Putln("// SequenceId returns the sequence id attached to the %s error.",
+		e.ErrConst())
+	c.Putln("// This is mostly used internally.")
 	c.Putln("func (err %s) SequenceId() uint16 {", e.ErrType())
 	c.Putln("return err.Sequence")
 	c.Putln("}")
@@ -84,8 +84,7 @@ func (e *Error) ImplementsError(c *Context) {
 
 // ErrorCopy types
 func (e *ErrorCopy) Define(c *Context) {
-	c.Putln("// ErrorCopy definition %s (%d)", e.SrcName(), e.Number)
-	c.Putln("")
+	c.Putln("// %s is the error number for a %s.", e.ErrConst(), e.ErrConst())
 	c.Putln("const %s = %d", e.ErrConst(), e.Number)
 	c.Putln("")
 	c.Putln("type %s %s", e.ErrType(), e.Old.(*Error).ErrType())
@@ -111,6 +110,8 @@ func (e *ErrorCopy) Define(c *Context) {
 }
 
 func (e *ErrorCopy) Read(c *Context) {
+	c.Putln("// %sNew constructs a %s value that implements xgb.Error from "+
+		"a byte slice.", e.ErrType(), e.ErrType())
 	c.Putln("func %sNew(buf []byte) xgb.Error {", e.ErrType())
 	c.Putln("v := %s(%sNew(buf).(%s))",
 		e.ErrType(), e.Old.(*Error).ErrType(), e.Old.(*Error).ErrType())
@@ -122,8 +123,9 @@ func (e *ErrorCopy) Read(c *Context) {
 
 // ImplementsError writes functions to implement the XGB Error interface.
 func (e *ErrorCopy) ImplementsError(c *Context) {
-	c.Putln("func (err %s) ImplementsError() { }", e.ErrType())
-	c.Putln("")
+	c.Putln("// SequenceId returns the sequence id attached to the %s error.",
+		e.ErrConst())
+	c.Putln("// This is mostly used internally.")
 	c.Putln("func (err %s) SequenceId() uint16 {", e.ErrType())
 	c.Putln("return err.Sequence")
 	c.Putln("}")
diff --git a/nexgb/xgbgen/go_event.go b/nexgb/xgbgen/go_event.go
index d7ef109..9b5e748 100644
--- a/nexgb/xgbgen/go_event.go
+++ b/nexgb/xgbgen/go_event.go
@@ -6,9 +6,7 @@ import (
 
 // Event types
 func (e *Event) Define(c *Context) {
-	c.Putln("// Event definition %s (%d)", e.SrcName(), e.Number)
-	c.Putln("// Size: %s", e.Size())
-	c.Putln("")
+	c.Putln("// %s is the event number for a %s.", e.SrcName(), e.EvType())
 	c.Putln("const %s = %d", e.SrcName(), e.Number)
 	c.Putln("")
 	c.Putln("type %s struct {", e.EvType())
@@ -30,8 +28,10 @@ func (e *Event) Define(c *Context) {
 	e.Write(c)
 
 	// Makes sure that this event type is an Event interface.
-	c.Putln("func (v %s) ImplementsEvent() { }", e.EvType())
-	c.Putln("")
+	c.Putln("// SequenceId returns the sequence id attached to the %s event.",
+		e.SrcName())
+	c.Putln("// Events without a sequence number (KeymapNotify) return 0.")
+	c.Putln("// This is mostly used internally.")
 	c.Putln("func (v %s) SequenceId() uint16 {", e.EvType())
 	if e.NoSequence {
 		c.Putln("return uint16(0)")
@@ -40,6 +40,8 @@ func (e *Event) Define(c *Context) {
 	}
 	c.Putln("}")
 	c.Putln("")
+	c.Putln("// String is a rudimentary string representation of %s.",
+		e.EvType())
 	c.Putln("func (v %s) String() string {", e.EvType())
 	EventFieldString(c, e.Fields, e.SrcName())
 	c.Putln("}")
@@ -58,7 +60,8 @@ func (e *Event) Define(c *Context) {
 }
 
 func (e *Event) Read(c *Context) {
-	c.Putln("// Event read %s", e.SrcName())
+	c.Putln("// %sNew constructs a %s value that implements xgb.Event from "+
+		"a byte slice.", e.EvType(), e.EvType())
 	c.Putln("func %sNew(buf []byte) xgb.Event {", e.EvType())
 	c.Putln("v := %s{}", e.EvType())
 	c.Putln("b := 1 // don't read event number")
@@ -78,7 +81,7 @@ func (e *Event) Read(c *Context) {
 }
 
 func (e *Event) Write(c *Context) {
-	c.Putln("// Event write %s", e.SrcName())
+	c.Putln("// Bytes writes a %s value to a byte slice.", e.EvType())
 	c.Putln("func (v %s) Bytes() []byte {", e.EvType())
 	c.Putln("buf := make([]byte, %s)", e.Size())
 	c.Putln("b := 0")
@@ -102,8 +105,7 @@ func (e *Event) Write(c *Context) {
 
 // EventCopy types
 func (e *EventCopy) Define(c *Context) {
-	c.Putln("// EventCopy definition %s (%d)", e.SrcName(), e.Number)
-	c.Putln("")
+	c.Putln("// %s is the event number for a %s.", e.SrcName(), e.EvType())
 	c.Putln("const %s = %d", e.SrcName(), e.Number)
 	c.Putln("")
 	c.Putln("type %s %s", e.EvType(), e.Old.(*Event).EvType())
@@ -118,8 +120,10 @@ func (e *EventCopy) Define(c *Context) {
 	e.Write(c)
 
 	// Makes sure that this event type is an Event interface.
-	c.Putln("func (v %s) ImplementsEvent() { }", e.EvType())
-	c.Putln("")
+	c.Putln("// SequenceId returns the sequence id attached to the %s event.",
+		e.SrcName())
+	c.Putln("// Events without a sequence number (KeymapNotify) return 0.")
+	c.Putln("// This is mostly used internally.")
 	c.Putln("func (v %s) SequenceId() uint16 {", e.EvType())
 	if e.Old.(*Event).NoSequence {
 		c.Putln("return uint16(0)")
@@ -146,6 +150,8 @@ func (e *EventCopy) Define(c *Context) {
 }
 
 func (e *EventCopy) Read(c *Context) {
+	c.Putln("// %sNew constructs a %s value that implements xgb.Event from "+
+		"a byte slice.", e.EvType(), e.EvType())
 	c.Putln("func %sNew(buf []byte) xgb.Event {", e.EvType())
 	c.Putln("return %s(%sNew(buf).(%s))",
 		e.EvType(), e.Old.(*Event).EvType(), e.Old.(*Event).EvType())
@@ -154,6 +160,7 @@ func (e *EventCopy) Read(c *Context) {
 }
 
 func (e *EventCopy) Write(c *Context) {
+	c.Putln("// Bytes writes a %s value to a byte slice.", e.EvType())
 	c.Putln("func (v %s) Bytes() []byte {", e.EvType())
 	c.Putln("return %s(v).Bytes()", e.Old.(*Event).EvType())
 	c.Putln("}")
diff --git a/nexgb/xgbgen/go_request_reply.go b/nexgb/xgbgen/go_request_reply.go
index 200260c..eca0c10 100644
--- a/nexgb/xgbgen/go_request_reply.go
+++ b/nexgb/xgbgen/go_request_reply.go
@@ -6,13 +6,16 @@ import (
 )
 
 func (r *Request) Define(c *Context) {
-	c.Putln("// Request %s", r.SrcName())
-	c.Putln("// size: %s", r.Size(c))
+	c.Putln("// %s is a cookie used only for %s requests.",
+		r.CookieName(), r.SrcName())
 	c.Putln("type %s struct {", r.CookieName())
 	c.Putln("*xgb.Cookie")
 	c.Putln("}")
 	c.Putln("")
 	if r.Reply != nil {
+		c.Putln("// %s sends a checked request.", r.SrcName())
+		c.Putln("// If an error occurs, it will be returned with the reply "+
+			"by calling %s.Reply()", r.CookieName())
 		c.Putln("func %s(c *xgb.Conn, %s) %s {",
 			r.SrcName(), r.ParamNameTypes(), r.CookieName())
 		c.Putln("cookie := c.NewCookie(true, true)")
@@ -21,6 +24,9 @@ func (r *Request) Define(c *Context) {
 		c.Putln("}")
 		c.Putln("")
 
+		c.Putln("// %sUnchecked sends an unchecked request.", r.SrcName())
+		c.Putln("// If an error occurs, it can only be retrieved using " +
+			"xgb.WaitForEvent or xgb.PollForEvent.")
 		c.Putln("func %sUnchecked(c *xgb.Conn, %s) %s {",
 			r.SrcName(), r.ParamNameTypes(), r.CookieName())
 		c.Putln("cookie := c.NewCookie(false, true)")
@@ -31,7 +37,9 @@ func (r *Request) Define(c *Context) {
 
 		r.ReadReply(c)
 	} else {
-		c.Putln("// Write request to wire for %s", r.SrcName())
+		c.Putln("// %s sends an unchecked request.", r.SrcName())
+		c.Putln("// If an error occurs, it can only be retrieved using " +
+			"xgb.WaitForEvent or xgb.PollForEvent.")
 		c.Putln("func %s(c *xgb.Conn, %s) %s {",
 			r.SrcName(), r.ParamNameTypes(), r.CookieName())
 		c.Putln("cookie := c.NewCookie(false, false)")
@@ -40,6 +48,9 @@ func (r *Request) Define(c *Context) {
 		c.Putln("}")
 		c.Putln("")
 
+		c.Putln("// %sChecked sends a checked request.", r.SrcName())
+		c.Putln("// If an error occurs, it can be retrieved using "+
+			"%s.Check()", r.CookieName())
 		c.Putln("func %sChecked(c *xgb.Conn, %s) %s {",
 			r.SrcName(), r.ParamNameTypes(), r.CookieName())
 		c.Putln("cookie := c.NewCookie(true, false)")
@@ -48,6 +59,10 @@ func (r *Request) Define(c *Context) {
 		c.Putln("}")
 		c.Putln("")
 
+		c.Putln("// Check returns an error if one occurred for checked " +
+			"requests that are not expecting a reply.")
+		c.Putln("// This cannot be called for requests expecting a reply, " +
+			"nor for unchecked requests.")
 		c.Putln("func (cook %s) Check() error {", r.CookieName())
 		c.Putln("return cook.Cookie.Check()")
 		c.Putln("}")
@@ -57,18 +72,19 @@ func (r *Request) Define(c *Context) {
 }
 
 func (r *Request) ReadReply(c *Context) {
-	c.Putln("// Request reply for %s", r.SrcName())
-	c.Putln("// size: %s", r.Reply.Size())
+	c.Putln("// %s represents the data returned from a %s request.",
+		r.ReplyTypeName(), r.SrcName())
 	c.Putln("type %s struct {", r.ReplyTypeName())
-	c.Putln("Sequence uint16")
-	c.Putln("Length uint32")
+	c.Putln("Sequence uint16 // sequence number of the request for this reply")
+	c.Putln("Length uint32 // number of bytes in this reply")
 	for _, field := range r.Reply.Fields {
 		field.Define(c)
 	}
 	c.Putln("}")
 	c.Putln("")
 
-	c.Putln("// Waits and reads reply data from request %s", r.SrcName())
+	c.Putln("// Reply blocks and returns the reply data for a %s request.",
+		r.SrcName())
 	c.Putln("func (cook %s) Reply() (*%s, error) {",
 		r.CookieName(), r.ReplyTypeName())
 	c.Putln("buf, err := cook.Cookie.Reply()")
@@ -82,7 +98,8 @@ func (r *Request) ReadReply(c *Context) {
 	c.Putln("}")
 	c.Putln("")
 
-	c.Putln("// Read reply into structure from buffer for %s", r.SrcName())
+	c.Putln("// %s reads a byte slice into a %s value.",
+		r.ReplyName(), r.ReplyTypeName())
 	c.Putln("func %s(buf []byte) *%s {",
 		r.ReplyName(), r.ReplyTypeName())
 	c.Putln("v := new(%s)", r.ReplyTypeName())
@@ -113,6 +130,8 @@ func (r *Request) WriteRequest(c *Context) {
 		c.Putln("")
 	}
 	c.Putln("// Write request to wire for %s", r.SrcName())
+	c.Putln("// %s writes a %s request to a byte slice.",
+		r.ReqName(), r.SrcName())
 	c.Putln("func %s(c *xgb.Conn, %s) []byte {",
 		r.ReqName(), r.ParamNameTypes())
 	c.Putln("size := %s", r.Size(c))
diff --git a/nexgb/xgbgen/go_struct.go b/nexgb/xgbgen/go_struct.go
index 7f33b21..a988893 100644
--- a/nexgb/xgbgen/go_struct.go
+++ b/nexgb/xgbgen/go_struct.go
@@ -1,8 +1,6 @@
 package main
 
 func (s *Struct) Define(c *Context) {
-	c.Putln("// '%s' struct definition", s.SrcName())
-	c.Putln("// Size: %s", s.Size())
 	c.Putln("type %s struct {", s.SrcName())
 	for _, field := range s.Fields {
 		field.Define(c)
@@ -34,7 +32,8 @@ func (s *Struct) Define(c *Context) {
 // the number of bytes read off the buffer.
 // 'ReadStructName' should only be used to read raw reply data from the wire.
 func (s *Struct) Read(c *Context) {
-	c.Putln("// Struct read %s", s.SrcName())
+	c.Putln("// %sRead reads a byte slice into a %s value.",
+		s.SrcName(), s.SrcName())
 	c.Putln("func %sRead(buf []byte, v *%s) int {", s.SrcName(), s.SrcName())
 
 	c.Putln("b := 0")
@@ -53,10 +52,10 @@ func (s *Struct) Read(c *Context) {
 // a source (i.e., the buffer) byte slice, and a destination slice and returns 
 // the number of bytes read from the byte slice.
 func (s *Struct) ReadList(c *Context) {
-	c.Putln("// Struct list read %s", s.SrcName())
+	c.Putln("// %sReadList reads a byte slice into a list of %s values.",
+		s.SrcName(), s.SrcName())
 	c.Putln("func %sReadList(buf []byte, dest []%s) int {",
 		s.SrcName(), s.SrcName())
-
 	c.Putln("b := 0")
 	c.Putln("for i := 0; i < len(dest); i++ {")
 	c.Putln("dest[i] = %s{}", s.SrcName())
@@ -70,7 +69,7 @@ func (s *Struct) ReadList(c *Context) {
 }
 
 func (s *Struct) Write(c *Context) {
-	c.Putln("// Struct write %s", s.SrcName())
+	c.Putln("// Bytes writes a %s value to a byte slice.", s.SrcName())
 	c.Putln("func (v %s) Bytes() []byte {", s.SrcName())
 	c.Putln("buf := make([]byte, %s)", s.Size().Reduce("v."))
 	c.Putln("b := 0")
@@ -85,7 +84,8 @@ func (s *Struct) Write(c *Context) {
 }
 
 func (s *Struct) WriteList(c *Context) {
-	c.Putln("// Write struct list %s", s.SrcName())
+	c.Putln("// %sListBytes writes a list of %s values to a byte slice.",
+		s.SrcName())
 	c.Putln("func %sListBytes(buf []byte, list []%s) int {",
 		s.SrcName(), s.SrcName())
 	c.Putln("b := 0")
@@ -101,7 +101,8 @@ func (s *Struct) WriteList(c *Context) {
 }
 
 func (s *Struct) WriteListSize(c *Context) {
-	c.Putln("// Struct list size %s", s.SrcName())
+	c.Putln("// %sListSize computes the size (bytes) of a list of %s values.",
+		s.SrcName(), s.SrcName())
 	c.Putln("func %sListSize(list []%s) int {", s.SrcName(), s.SrcName())
 	c.Putln("size := 0")
 	if s.Size().Expression.Concrete() {
diff --git a/nexgb/xgbgen/go_union.go b/nexgb/xgbgen/go_union.go
index 91300a2..1a8684c 100644
--- a/nexgb/xgbgen/go_union.go
+++ b/nexgb/xgbgen/go_union.go
@@ -2,7 +2,8 @@ package main
 
 // Union types
 func (u *Union) Define(c *Context) {
-	c.Putln("// Union definition %s", u.SrcName())
+	c.Putln("// %s is a represention of the %s union type.",
+		u.SrcName(), u.SrcName())
 	c.Putln("// Note that to *create* a Union, you should *never* create")
 	c.Putln("// this struct directly (unless you know what you're doing).")
 	c.Putln("// Instead use one of the following constructors for '%s':",
@@ -38,8 +39,8 @@ func (u *Union) Define(c *Context) {
 
 func (u *Union) New(c *Context) {
 	for _, field := range u.Fields {
-		c.Putln("// Union constructor for %s for field %s.",
-			u.SrcName(), field.SrcName())
+		c.Putln("// %s%sNew constructs a new %s union type with the %s field.",
+			u.SrcName(), field.SrcName(), u.SrcName(), field.SrcName())
 		c.Putln("func %s%sNew(%s %s) %s {",
 			u.SrcName(), field.SrcName(), field.SrcName(),
 			field.SrcType(), u.SrcName())
@@ -65,7 +66,8 @@ func (u *Union) New(c *Context) {
 }
 
 func (u *Union) Read(c *Context) {
-	c.Putln("// Union read %s", u.SrcName())
+	c.Putln("// %sRead reads a byte slice into a %s value.",
+		u.SrcName(), u.SrcName())
 	c.Putln("func %sRead(buf []byte, v *%s) int {", u.SrcName(), u.SrcName())
 	c.Putln("var b int")
 	c.Putln("")
@@ -80,7 +82,8 @@ func (u *Union) Read(c *Context) {
 }
 
 func (u *Union) ReadList(c *Context) {
-	c.Putln("// Union list read %s", u.SrcName())
+	c.Putln("// %sReadList reads a byte slice into a list of %s values.",
+		u.SrcName(), u.SrcName())
 	c.Putln("func %sReadList(buf []byte, dest []%s) int {",
 		u.SrcName(), u.SrcName())
 	c.Putln("b := 0")
@@ -99,7 +102,7 @@ func (u *Union) ReadList(c *Context) {
 // *same* *fixed* size. Thus, we make sure to always read bytes into
 // every field which allows us to simply pick the first field and write it.
 func (u *Union) Write(c *Context) {
-	c.Putln("// Union write %s", u.SrcName())
+	c.Putln("// Bytes writes a %s value to a byte slice.", u.SrcName())
 	c.Putln("// Each field in a union must contain the same data.")
 	c.Putln("// So simply pick the first field and write that to the wire.")
 	c.Putln("func (v %s) Bytes() []byte {", u.SrcName())
@@ -113,7 +116,8 @@ func (u *Union) Write(c *Context) {
 }
 
 func (u *Union) WriteList(c *Context) {
-	c.Putln("// Union list write %s", u.SrcName())
+	c.Putln("// %sListBytes writes a list of %s values to a byte slice.",
+		u.SrcName())
 	c.Putln("func %sListBytes(buf []byte, list []%s) int {",
 		u.SrcName(), u.SrcName())
 	c.Putln("b := 0")
@@ -130,6 +134,8 @@ func (u *Union) WriteList(c *Context) {
 
 func (u *Union) WriteListSize(c *Context) {
 	c.Putln("// Union list size %s", u.SrcName())
+	c.Putln("// %sListSize computes the size (bytes) of a list of %s values.",
+		u.SrcName())
 	c.Putln("func %sListSize(list []%s) int {", u.SrcName(), u.SrcName())
 	c.Putln("size := 0")
 	c.Putln("for _, item := range list {")