better docs

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() {