From 2e250a6f4c1f654783e93229e6c0f102017b2224 Mon Sep 17 00:00:00 2001
From: Michael McLoughlin <mmcloughlin@gmail.com>
Date: Fri, 4 Jan 2019 21:38:23 -0800
Subject: [PATCH] operand: doc for exported symbols (#9)

---
 operand/const.go |  9 +++++++--
 operand/types.go | 13 ++++++++++++-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/operand/const.go b/operand/const.go
index e465275..8163dc9 100644
--- a/operand/const.go
+++ b/operand/const.go
@@ -2,6 +2,7 @@ package operand
 
 import "fmt"
 
+// Constant represents a constant literal.
 type Constant interface {
 	Op
 	Bytes() int
@@ -13,9 +14,13 @@ type Constant interface {
 // String is a string constant.
 type String string
 
+// Asm returns an assembly syntax representation of the string s.
 func (s String) Asm() string { return fmt.Sprintf("$%q", s) }
-func (s String) Bytes() int  { return len(s) }
-func (s String) constant()   {}
+
+// Bytes returns the length of s.
+func (s String) Bytes() int { return len(s) }
+
+func (s String) constant() {}
 
 // Imm returns an unsigned integer constant with size guessed from x.
 func Imm(x uint64) Constant {
diff --git a/operand/types.go b/operand/types.go
index c7788a1..f8cd956 100644
--- a/operand/types.go
+++ b/operand/types.go
@@ -6,15 +6,18 @@ import (
 	"github.com/mmcloughlin/avo/reg"
 )
 
+// Op is an operand.
 type Op interface {
 	Asm() string
 }
 
+// Symbol represents a symbol name.
 type Symbol struct {
 	Name   string
-	Static bool
+	Static bool // only visible in current source file
 }
 
+// NewStaticSymbol builds a static Symbol. Static symbols are only visible in the current source file.
 func NewStaticSymbol(name string) Symbol {
 	return Symbol{Name: name, Static: true}
 }
@@ -27,6 +30,7 @@ func (s Symbol) String() string {
 	return n
 }
 
+// Mem represents a memory reference.
 type Mem struct {
 	Symbol Symbol
 	Disp   int
@@ -48,6 +52,7 @@ func NewParamAddr(name string, offset int) Mem {
 	}
 }
 
+// NewStackAddr returns a memory reference relative to the stack pointer.
 func NewStackAddr(offset int) Mem {
 	return Mem{
 		Disp: offset,
@@ -55,6 +60,7 @@ func NewStackAddr(offset int) Mem {
 	}
 }
 
+// NewDataAddr returns a memory reference relative to the named data symbol.
 func NewDataAddr(sym Symbol, offset int) Mem {
 	return Mem{
 		Symbol: sym,
@@ -63,12 +69,14 @@ func NewDataAddr(sym Symbol, offset int) Mem {
 	}
 }
 
+// Offset returns a reference to m plus idx bytes.
 func (m Mem) Offset(idx int) Mem {
 	a := m
 	a.Disp += idx
 	return a
 }
 
+// Idx returns a new memory reference with (Index, Scale) set to (r, s).
 func (m Mem) Idx(r reg.Register, s uint8) Mem {
 	a := m
 	a.Index = r
@@ -76,6 +84,7 @@ func (m Mem) Idx(r reg.Register, s uint8) Mem {
 	return a
 }
 
+// Asm returns an assembly syntax representation of m.
 func (m Mem) Asm() string {
 	a := m.Symbol.String()
 	if m.Disp != 0 {
@@ -97,6 +106,7 @@ func (m Mem) Asm() string {
 // Rel is an offset relative to the instruction pointer.
 type Rel int32
 
+// Asm returns an assembly syntax representation of r.
 func (r Rel) Asm() string {
 	return fmt.Sprintf(".%+d", r)
 }
@@ -104,6 +114,7 @@ func (r Rel) Asm() string {
 // LabelRef is a reference to a label.
 type LabelRef string
 
+// Asm returns an assembly syntax representation of l.
 func (l LabelRef) Asm() string {
 	return string(l)
 }