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/xgbgen/go_union.go | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

(limited to 'nexgb/xgbgen/go_union.go')

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 {")
-- 
cgit v1.2.3-70-g09d2