From c00652934e4ec68016a152b9bea10273b0be8726 Mon Sep 17 00:00:00 2001 From: "Andrew Gallant (Ocelot)" Date: Thu, 10 May 2012 23:57:34 -0400 Subject: better docs --- nexgb/xgbgen/go_error.go | 22 ++++++++++++---------- nexgb/xgbgen/go_event.go | 29 ++++++++++++++++++----------- nexgb/xgbgen/go_request_reply.go | 37 ++++++++++++++++++++++++++++--------- nexgb/xgbgen/go_struct.go | 17 +++++++++-------- nexgb/xgbgen/go_union.go | 20 +++++++++++++------- 5 files changed, 80 insertions(+), 45 deletions(-) (limited to 'nexgb/xgbgen') 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 {") -- cgit v1.2.3