Merge pull request #183 from nyaruka/docstrings_etc

No more lint warnings - everything docstringed etc

cmd/flowserver/server.go

@@ -114,6 +114,7 @@ type sessionResponse struct {
 	Log     []flows.LogEntry `json:"log"`
 }
 
+// MarshalJSON marshals this session reponse into JSON
 func (r *sessionResponse) MarshalJSON() ([]byte, error) {
 	envelope := sessionResponse{
 		Session: r.Session,

excellent/functions_test.go

@@ -322,7 +322,7 @@ var funcTests = []struct {
 }
 
 func TestFunctions(t *testing.T) {
-	env := utils.NewEnvironment(utils.DateFormat_dd_MM_yyyy, utils.TimeFormat_HH_mm_ss, time.UTC, utils.LanguageList{})
+	env := utils.NewEnvironment(utils.DateFormatDayMonthYear, utils.TimeFormatHourMinuteSecond, time.UTC, utils.LanguageList{})
 
 	for _, test := range funcTests {
 		xFunc := XFUNCTIONS[test.name]
@@ -381,7 +381,7 @@ var rangeTests = []struct {
 }
 
 func TestRangeFunctions(t *testing.T) {
-	env := utils.NewEnvironment(utils.DateFormat_dd_MM_yyyy, utils.TimeFormat_HH_mm_ss, time.UTC, utils.LanguageList{})
+	env := utils.NewEnvironment(utils.DateFormatDayMonthYear, utils.TimeFormatHourMinuteSecond, time.UTC, utils.LanguageList{})
 
 	for _, test := range rangeTests {
 		xFunc := XFUNCTIONS[test.name]

excellent/legacy.go

@@ -17,6 +17,7 @@ var topLevelScopes = []string{"contact", "child", "parent", "run", "trigger"}
 // ExtraVarsMapping defines how @extra.* variables should be migrated
 type ExtraVarsMapping string
 
+// different ways of mapping @extra in legacy flows
 const (
 	ExtraAsWebhookJSON   ExtraVarsMapping = "run.webhook.json"
 	ExtraAsTriggerParams ExtraVarsMapping = "trigger.params"
@@ -57,6 +58,7 @@ func (v *varMapper) rebase(prefix string) *varMapper {
 	}
 }
 
+// Resolve resolves the given key to a mapped expression
 func (v *varMapper) Resolve(key string) interface{} {
 
 	// is this a complete substitution?
@@ -109,6 +111,7 @@ func (v *varMapper) Resolve(key string) interface{} {
 	return strings.Join(newPath, ".")
 }
 
+// Default returns the value of this mapper when it is the result of an expression
 func (v *varMapper) Default() interface{} {
 	return v.base
 }
@@ -129,6 +132,7 @@ type extraMapper struct {
 	extraAs ExtraVarsMapping
 }
 
+// Resolve resolves the given key to a new expression
 func (m *extraMapper) Resolve(key string) interface{} {
 	newPath := []string{}
 	if m.path != "" {
@@ -138,6 +142,7 @@ func (m *extraMapper) Resolve(key string) interface{} {
 	return &extraMapper{extraAs: m.extraAs, path: strings.Join(newPath, ".")}
 }
 
+// Default returns the value of this extra mapper when it is the result of an expression
 func (m *extraMapper) Default() interface{} {
 	return m
 }

excellent/tests.go

@@ -75,19 +75,18 @@ func (t XTestResult) Matched() bool { return t.matched }
 // Match returns the item which was matched
 func (t XTestResult) Match() interface{} { return t.match }
 
-// Resolve satisfies the utils.VariableResolver interface, users can look up the match or whether we matched
+// Resolve resolves the given key when this result is referenced in an expression
 func (t XTestResult) Resolve(key string) interface{} {
 	switch key {
 	case "matched":
 		return t.matched
-
 	case "match":
 		return t.match
 	}
 	return fmt.Errorf("no such key '%s' on test result", key)
 }
 
-// Default satisfies the utils.VariableResolver interface, we always default to whether we matched
+// Default returns the value of this result when it is the result of an expression
 func (t XTestResult) Default() interface{} {
 	return t.matched
 }
@@ -391,7 +390,7 @@ func HasBeginning(env utils.Environment, args ...interface{}) interface{} {
 // Returned by the has_pattern test as its match value
 type patternMatch []string
 
-// Resolve satisfies the utils.VariableResolver interface, users can look up a numbered matching group
+// Resolve resolves the given key when this match is referenced in an expression
 func (m patternMatch) Resolve(key string) interface{} {
 	switch key {
 	case "groups":
@@ -401,7 +400,7 @@ func (m patternMatch) Resolve(key string) interface{} {
 	return fmt.Errorf("no such key '%s' on pattern match", key)
 }
 
-// Default satisfies the utils.VariableResolver interface, and returns the group 0 match as the default value
+// Default returns the value of this match when it is the result of an expression
 func (m patternMatch) Default() interface{} {
 	return m[0]
 }

excellent/tests_test.go

@@ -169,7 +169,7 @@ var testTests = []struct {
 }
 
 func TestTests(t *testing.T) {
-	env := utils.NewEnvironment(utils.DateFormat_dd_MM_yyyy, utils.TimeFormat_HH_mm_ss, time.UTC, utils.LanguageList{})
+	env := utils.NewEnvironment(utils.DateFormatDayMonthYear, utils.TimeFormatHourMinuteSecond, time.UTC, utils.LanguageList{})
 
 	for _, test := range testTests {
 		testFunc := XTESTS[test.name]

flows/attachments.go

@@ -28,19 +28,19 @@ func (a Attachment) URL() string {
 	return string(a)
 }
 
+// Resolve resolves the given key when this attachment is referenced in an expression
 func (a Attachment) Resolve(key string) interface{} {
 	switch key {
-
 	case "content_type":
 		return a.ContentType()
-
 	case "url":
 		return a.URL()
 	}
 
 	return fmt.Errorf("No field '%s' on attachment", key)
 }
 
+// Default returns the value of this attachment when it is the result of an expression
 func (a Attachment) Default() interface{} { return a }
 func (a Attachment) String() string       { return a.URL() }
 

flows/channel.go

@@ -71,7 +71,7 @@ func (c *channel) HasRole(role ChannelRole) bool {
 	return false
 }
 
-// Resolve satisfies our resolver interface
+// Resolve resolves the given key when this channel is referenced in an expression
 func (c *channel) Resolve(key string) interface{} {
 	switch key {
 	case "uuid":
@@ -85,7 +85,7 @@ func (c *channel) Resolve(key string) interface{} {
 	return fmt.Errorf("No field '%s' on channel", key)
 }
 
-// Default returns the default value for a channel, which is itself
+// Default returns the value of this channel when it is the result of an expression
 func (c *channel) Default() interface{} {
 	return c
 }

flows/contact.go

@@ -105,6 +105,7 @@ func (c *Contact) Fields() FieldValues { return c.fields }
 // Reference returns a reference to this contact
 func (c *Contact) Reference() *ContactReference { return NewContactReference(c.uuid, c.name) }
 
+// Resolve resolves the given key when this contact is referenced in an expression
 func (c *Contact) Resolve(key string) interface{} {
 	switch key {
 	case "uuid":
@@ -137,7 +138,7 @@ func (c *Contact) Resolve(key string) interface{} {
 	return fmt.Errorf("no field '%s' on contact", key)
 }
 
-// Default returns our default value in the context
+// Default returns the value of this contact when it is the result of an expression
 func (c *Contact) Default() interface{} {
 	return c
 }
@@ -299,6 +300,7 @@ func ReadContact(session Session, data json.RawMessage) (*Contact, error) {
 	return c, nil
 }
 
+// MarshalJSON marshals this contact into JSON
 func (c *Contact) MarshalJSON() ([]byte, error) {
 	var ce contactEnvelope
 

flows/definition/flow.go

@@ -44,6 +44,7 @@ func (f *flow) Validate(assets flows.SessionAssets) error {
 	return err
 }
 
+// Resolve resolves the given key when this flow is referenced in an expression
 func (f *flow) Resolve(key string) interface{} {
 	switch key {
 	case "uuid":
@@ -55,6 +56,7 @@ func (f *flow) Resolve(key string) interface{} {
 	return fmt.Errorf("no field '%s' on flow", key)
 }
 
+// Default returns the value of this flow when it is the result of an expression
 func (f *flow) Default() interface{} {
 	return f
 }
@@ -135,6 +137,7 @@ func ReadFlow(data json.RawMessage) (flows.Flow, error) {
 	return f, nil
 }
 
+// MarshalJSON marshals this flow into JSON
 func (f *flow) MarshalJSON() ([]byte, error) {
 
 	var fe = flowEnvelope{}

flows/definition/legacy.go

@@ -18,6 +18,7 @@ import (
 // represents a decimal value which may be provided as a string or floating point value
 type decimalString string
 
+// UnmarshalJSON unmarshals a decimal string from the given JSON
 func (s *decimalString) UnmarshalJSON(data []byte) error {
 	if data[0] == '"' {
 		// data is a quoted string
@@ -101,6 +102,7 @@ func (l *legacyLabelReference) Migrate() *flows.LabelReference {
 	return flows.NewVariableLabelReference(l.Name)
 }
 
+// UnmarshalJSON unmarshals a legacy label reference from the given JSON
 func (l *legacyLabelReference) UnmarshalJSON(data []byte) error {
 	// label reference may be a string
 	if data[0] == '"' {
@@ -149,6 +151,7 @@ func (g *legacyGroupReference) Migrate() *flows.GroupReference {
 	return flows.NewVariableGroupReference(g.Name)
 }
 
+// UnmarshalJSON unmarshals a legacy group reference from the given JSON
 func (g *legacyGroupReference) UnmarshalJSON(data []byte) error {
 	// group reference may be a string
 	if data[0] == '"' {
@@ -998,7 +1001,7 @@ func ReadLegacyFlow(data json.RawMessage) (*LegacyFlow, error) {
 	return f, err
 }
 
-// MarshalJSON sends turns our legacy flow into bytes
+// MarshalJSON marshals this legacy flow into JSON
 func (f *LegacyFlow) MarshalJSON() ([]byte, error) {
 
 	var fe = flowEnvelope{}

flows/definition/node.go

@@ -2,7 +2,6 @@ package definition
 
 import (
 	"encoding/json"
-	"fmt"
 
 	"github.com/nyaruka/goflow/flows"
 	"github.com/nyaruka/goflow/flows/actions"
@@ -41,19 +40,6 @@ func (n *node) Actions() []flows.Action { return n.actions }
 func (n *node) Exits() []flows.Exit     { return n.exits }
 func (n *node) Wait() flows.Wait        { return n.wait }
 
-func (n *node) Resolve(key string) interface{} {
-	switch key {
-	case "uuid":
-		return n.uuid
-	}
-	return fmt.Errorf("No field '%s' on node", key)
-}
-
-func (n *node) Default() interface{} { return n.uuid }
-func (n *node) String() string       { return n.uuid.String() }
-
-var _ utils.VariableResolver = (*node)(nil)
-
 //------------------------------------------------------------------------------------------
 // JSON Encoding / Decoding
 //------------------------------------------------------------------------------------------
@@ -66,6 +52,7 @@ type nodeEnvelope struct {
 	Wait    *utils.TypedEnvelope   `json:"wait,omitempty"`
 }
 
+// UnmarshalJSON unmarshals a flow node from the given JSON
 func (n *node) UnmarshalJSON(data []byte) error {
 	var envelope nodeEnvelope
 	err := utils.UnmarshalAndValidate(data, &envelope, "node")
@@ -109,6 +96,7 @@ func (n *node) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// MarshalJSON marshals this flow node into JSON
 func (n *node) MarshalJSON() ([]byte, error) {
 	envelope := nodeEnvelope{}
 	var err error
@@ -148,6 +136,7 @@ type exitEnvelope struct {
 	Name                string         `json:"name,omitempty"`
 }
 
+// UnmarshalJSON unmarshals a node exit from the given JSON
 func (e *exit) UnmarshalJSON(data []byte) error {
 	var envelope exitEnvelope
 	err := utils.UnmarshalAndValidate(data, &envelope, "exit")
@@ -162,6 +151,7 @@ func (e *exit) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// MarshalJSON marshals this node exit into JSON
 func (e *exit) MarshalJSON() ([]byte, error) {
 	envelope := exitEnvelope{e.uuid, e.destination, e.name}
 	return json.Marshal(envelope)

flows/engine/assets.go

@@ -243,6 +243,7 @@ func (s *mockAssetServer) fetchAsset(url string, itemType assetType, isSet bool,
 	return readAsset(assetBuf, itemType, isSet)
 }
 
+// MarshalJSON marshals this mock asset server into JSON
 func (s *mockAssetServer) MarshalJSON() ([]byte, error) {
 	envelope := &assetServerEnvelope{}
 	envelope.TypeURLs = s.typeURLs

flows/engine/log.go

@@ -32,6 +32,7 @@ type logEntryEnvelope struct {
 	Event      *utils.TypedEnvelope `json:"event" validate:"required"`
 }
 
+// MarshalJSON marshals this log entry into JSON
 func (s *logEntry) MarshalJSON() ([]byte, error) {
 	var se logEntryEnvelope
 

flows/engine/session.go

@@ -531,6 +531,7 @@ func ReadSession(assetCache *AssetCache, assetServer AssetServer, data json.RawM
 	return s, nil
 }
 
+// MarshalJSON marshals this session into JSON
 func (s *session) MarshalJSON() ([]byte, error) {
 	var envelope sessionEnvelope
 	var err error

flows/fields.go

@@ -82,6 +82,7 @@ func NewFieldValue(field *Field, value interface{}, createdOn time.Time) *FieldV
 	return &FieldValue{field: field, value: value, createdOn: createdOn}
 }
 
+// Resolve resolves the given key when this field value is referenced in an expression
 func (v *FieldValue) Resolve(key string) interface{} {
 	switch key {
 	case "value":
@@ -92,7 +93,7 @@ func (v *FieldValue) Resolve(key string) interface{} {
 	return fmt.Errorf("no field '%s' on field value", key)
 }
 
-// Default returns the default value for FieldValue, which is the value
+// Default returns the value of this field value when it is the result of an expression
 func (v *FieldValue) Default() interface{} {
 	return v.value
 }
@@ -138,11 +139,12 @@ func (f FieldValues) Save(env utils.Environment, field *Field, rawValue string)
 	return nil
 }
 
+// Resolve resolves the given key when this set of field values is referenced in an expression
 func (f FieldValues) Resolve(key string) interface{} {
 	return f[FieldKey(key)]
 }
 
-// Default returns the default value for FieldValues, which is ourselves
+// Default returns the value of this set of field values when it is the result of an expression
 func (f FieldValues) Default() interface{} {
 	return f
 }

flows/group.go

@@ -60,7 +60,7 @@ func (g *Group) CheckDynamicMembership(session Session, contact *Contact) (bool,
 
 func (g *Group) Reference() *GroupReference { return NewGroupReference(g.uuid, g.name) }
 
-// Resolve resolves the passed in key to a value
+// Resolve resolves the given key when this group is referenced in an expression
 func (g *Group) Resolve(key string) interface{} {
 	switch key {
 	case "uuid":
@@ -72,7 +72,7 @@ func (g *Group) Resolve(key string) interface{} {
 	return fmt.Errorf("no field '%s' on group", key)
 }
 
-// Default returns the default value for this group
+// Default returns the value of this group when it is the result of an expression
 func (g *Group) Default() interface{} { return g }
 
 // String satisfies the stringer interface returning the name of the group
@@ -131,7 +131,7 @@ func (l *GroupList) Count() int {
 	return len(l.groups)
 }
 
-// Resolve looks up the passed in key for the group list, which must be either "count" or a numerical index
+// Resolve resolves the given key when this group list is referenced in an expression
 func (l *GroupList) Resolve(key string) interface{} {
 	if key == "count" {
 		return l.Count()
@@ -148,7 +148,7 @@ func (l *GroupList) Resolve(key string) interface{} {
 	return nil
 }
 
-// Default returns the default value for this group, which is our entire list
+// Default returns the value of this group list when it is the result of an expression
 func (l GroupList) Default() interface{} {
 	return l
 }

flows/inputs/base.go

@@ -17,7 +17,7 @@ func (i *baseInput) UUID() flows.InputUUID  { return i.uuid }
 func (i *baseInput) Channel() flows.Channel { return i.channel }
 func (i *baseInput) CreatedOn() time.Time   { return i.createdOn }
 
-// Resolve resolves the passed in key to a value, returning an error if the key is unknown
+// Resolve resolves the given key when this input is referenced in an expression
 func (i *baseInput) Resolve(key string) interface{} {
 	switch key {
 	case "uuid":