Merge pull request #21 from jattento/feature/add-documentation-to-remaining-api-elements

jattento · web-flow · commit 35b29de64dbb · 2020-10-27T00:41:48.000-03:00
add documentation to remaining api elements
diff --git a/Makefile b/Makefile
@@ -1,7 +1,7 @@
 ### Required tools
 GOTOOLS_CHECK = go golangci-lint
 
-all: ensure-deps linter test
+all: ensure-deps linter test gofmt
 
 ### Testing
 test:
@@ -23,7 +23,12 @@ linter:
 	@echo "==> Running linter"
 	golangci-lint run ./...
 
+gofmt:
+	@echo "==> Running go fmt"
+	go fmt ./...
+
+
 # To avoid unintended conflicts with file names, always add to .PHONY
 # unless there is a reason not to.
 # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
-.PHONY: all check_tools test test-cover linter ensure-deps
+.PHONY: all check_tools test test-cover linter ensure-deps gofmt
diff --git a/pkg/bitmap/bitmap.go b/pkg/bitmap/bitmap.go
@@ -6,6 +6,7 @@ import (
 	"math"
 )
 
+// Bitmap is a alias for map[int]bool used for better code reading.
 type Bitmap = map[int]bool
 
 const (
@@ -18,10 +19,13 @@ const (
 )
 
 var (
-	// Errors...
-	ErrBitmapISOWrongLength        = errors.New("wrong bitmap length input")
-	ErrBitmapISOBadBitmapPosition  = errors.New("bad bitmap position input")
-	ErrBitmapISOImpossibleBitmap   = errors.New("impossible generate bitmap, lowest and highest limits too far")
+	// ErrBitmapISOWrongLength exported error for asserting.
+	ErrBitmapISOWrongLength = errors.New("wrong bitmap length input")
+	// ErrBitmapISOBadBitmapPosition exported error for asserting.
+	ErrBitmapISOBadBitmapPosition = errors.New("bad bitmap position input")
+	// ErrBitmapISOImpossibleBitmap exported error for asserting.
+	ErrBitmapISOImpossibleBitmap = errors.New("impossible generate bitmap, lowest and highest limits too far")
+	// ErrBitmapISOFirstBitProhibited exported error for asserting.
 	ErrBitmapISOFirstBitProhibited = errors.New("first bit can be setted manually in input")
 )
 
@@ -137,6 +141,7 @@ func setBit(n byte, pos uint) byte {
 	return n
 }
 
+// Extremities returns the lowest and highest elements of a bitmap.
 func Extremities(b Bitmap) (low, high int) {
 	firstIteration := true
 	for k := range b {
diff --git a/pkg/encoding/ebcdic/1047.go b/pkg/encoding/ebcdic/1047.go
@@ -1,5 +1,6 @@
 package ebcdic
 
+// V1047 version of EBCDIC encoding
 var V1047 = version{entries: []entry{
 	{0x00, 0x00, 0x0},  // "NULL"
 	{0x01, 0x01, 0x0},  // "START OF HEADING"
diff --git a/pkg/encoding/ebcdic/ebcdic.go b/pkg/encoding/ebcdic/ebcdic.go
@@ -14,6 +14,7 @@ type entry struct {
 	representation rune
 }
 
+// NULL is used for invalid encoding conversions.
 const NULL = 0x0
 
 // FromGoString converts a string to ebcdic bytes.
@@ -37,7 +38,7 @@ func (v *version) FromGoString(s string) []byte {
 	return output
 }
 
-// FromGoString converts a ebcdic bytes to a string.
+// ToGoString converts a ebcdic bytes to a string.
 func (v *version) ToGoString(b []byte) string {
 	if len(v.decoding) == 0 {
 		v.generateDecodingMap()
diff --git a/pkg/iso8583/bitmap.go b/pkg/iso8583/bitmap.go
@@ -31,7 +31,7 @@ func (b BITMAP) MarshalISO8583(length int, encoding string) ([]byte, error) {
 	return bitmap.ToBytes(b.Bitmap), nil
 }
 
-// Returns which bits are on, key values are between 1 and 64, both included.
+// Bits returns which bits are on, key values are between 1 and 64, both included.
 // First value is bit 1.
 func (b BITMAP) Bits() (map[int]bool, error) {
 	return b.Bitmap, nil
diff --git a/pkg/iso8583/decode.go b/pkg/iso8583/decode.go
@@ -32,7 +32,7 @@ type Unmarshaler interface {
 	UnmarshalISO8583(b []byte, length int, encoding string) (n int, err error)
 }
 
-// Unmarshaler interface for iso8583 bitmaps.
+// UnmarshalerBitmap is the unmarshaler interface for iso8583 bitmaps.
 //
 // Length tag: It indicates the amount of representative bits contained
 // by the bitmap. For example in a classic 8 byte bitmap it would be 64,
@@ -160,7 +160,7 @@ func newUnmarshalBuffer(data []byte) *unmarshalBuffer {
 	return &buffer
 }
 
-// incrementConsumed increments the placeholder considering the data length.
+// IncrementConsumedCounter increments the placeholder considering the data length.
 func (buffer *unmarshalBuffer) IncrementConsumedCounter(n int, fieldName string) error {
 	if len(buffer.data[buffer.placeholder:]) < n {
 		// This error can only be caused by bad unmarshal implementations
diff --git a/pkg/iso8583/decode_test.go b/pkg/iso8583/decode_test.go
@@ -43,7 +43,7 @@ func TestUnmarshal(t *testing.T) {
 				field3 iso8583.VAR    `iso8583:"3,length:3"`
 			}{
 				Field2: "asd",
-				Bitmap: iso8583.BITMAP{map[int]bool{1: false, 2: true, 3: false, 4: false, 5: false, 6: false,
+				Bitmap: iso8583.BITMAP{Bitmap: map[int]bool{1: false, 2: true, 3: false, 4: false, 5: false, 6: false,
 					7: false, 8: false, 9: false, 10: false, 11: false, 12: false, 13: false, 14: false, 15: false,
 					16: false, 17: false, 18: false, 19: false, 20: false, 21: false, 22: false, 23: false, 24: false,
 					25: false, 26: false, 27: false, 28: false, 29: false, 30: false, 31: false, 32: false, 33: false,
@@ -77,15 +77,15 @@ func TestUnmarshal(t *testing.T) {
 			}{
 				Field2:  "asd",
 				Field66: "fgh",
-				Field1: iso8583.BITMAP{map[int]bool{1: false, 2: true, 3: false, 4: false, 5: false, 6: false,
+				Field1: iso8583.BITMAP{Bitmap: map[int]bool{1: false, 2: true, 3: false, 4: false, 5: false, 6: false,
 					7: false, 8: false, 9: false, 10: false, 11: false, 12: false, 13: false, 14: false, 15: false,
 					16: false, 17: false, 18: false, 19: false, 20: false, 21: false, 22: false, 23: false, 24: false,
 					25: false, 26: false, 27: false, 28: false, 29: false, 30: false, 31: false, 32: false, 33: false,
 					34: false, 35: false, 36: false, 37: false, 38: false, 39: false, 40: false, 41: false, 42: false,
 					43: false, 44: false, 45: false, 46: false, 47: false, 48: false, 49: false, 50: false, 51: false,
 					52: false, 53: false, 54: false, 55: false, 56: false, 57: false, 58: false, 59: false, 60: false,
 					61: false, 62: false, 63: false, 64: false}},
-				Bitmap: iso8583.BITMAP{map[int]bool{1: true, 2: true, 3: false, 4: false, 5: false, 6: false,
+				Bitmap: iso8583.BITMAP{Bitmap: map[int]bool{1: true, 2: true, 3: false, 4: false, 5: false, 6: false,
 					7: false, 8: false, 9: false, 10: false, 11: false, 12: false, 13: false, 14: false, 15: false,
 					16: false, 17: false, 18: false, 19: false, 20: false, 21: false, 22: false, 23: false, 24: false,
 					25: false, 26: false, 27: false, 28: false, 29: false, 30: false, 31: false, 32: false, 33: false,
diff --git a/pkg/iso8583/encode.go b/pkg/iso8583/encode.go
@@ -44,6 +44,7 @@ type Marshaler interface {
 // Omitempty tag does not affect MarshalerBitmap.
 // NOTE: This implementation is not a must in bitmaps.
 type MarshalerBitmap interface {
+	// MarshalISO8583Bitmap must consume b map information and return the corresponding byte slice.
 	// b should always represent which bits are on what not necessarily is equal to what fields are present.
 	// For example: In a traditional 8 byte bitmap. Te presence of field 65 would be represented in with bit 1 on.
 	// len(b) == length tag.
diff --git a/pkg/iso8583/encoding.go b/pkg/iso8583/encoding.go
@@ -4,11 +4,13 @@ import (
 	"github.com/jattento/go-iso8583/pkg/encoding/ebcdic"
 )
 
+// UnmarshalDecodings is the unmarshal encodings map used by inbuilt ISO fields, you can append more encoding for extended functionality.
 var UnmarshalDecodings = map[string]func([]byte) ([]byte, error){
 	"ebcdic": errWrapper(func(bytes []byte) []byte { return []byte(ebcdic.V1047.ToGoString(bytes)) }),
 	"ascii":  nop,
 }
 
+// MarshalEncodings is the marshal encodings map used by inbuilt ISO fields, you can append more encoding for extended functionality.
 var MarshalEncodings = map[string]func([]byte) ([]byte, error){
 	"ebcdic": errWrapper(func(bytes []byte) []byte {
 		return ebcdic.V1047.FromGoString(string(bytes))
diff --git a/pkg/iso8583/lllvar.go b/pkg/iso8583/lllvar.go
@@ -4,7 +4,8 @@ import (
 	"errors"
 )
 
-// LLLVAR: For use of different encoding for 'LLL' and 'VAR' separate both encodings with a slash,
+// LLLVAR field type.
+// For use of different encoding for 'LLL' and 'VAR' separate both encodings with a slash,
 // where first element is the lll encoding and the second the var encoding.
 // For Unmarshal length indicate the amount of byte that contain the LLL value
 // For example:
diff --git a/pkg/iso8583/llvar.go b/pkg/iso8583/llvar.go
@@ -8,7 +8,8 @@ import (
 	"unicode"
 )
 
-// LLVAR: For use of different encoding for 'LL' and 'VAR' separate both encodings with a slash,
+// LLVAR field type.
+// For use of different encoding for 'LL' and 'VAR' separate both encodings with a slash,
 // where first element is the ll encoding and the second the var encoding.
 // For Unmarshal length indicate the amount of byte that contain the LL value
 // For example:
diff --git a/pkg/mti/mti.go b/pkg/mti/mti.go
@@ -73,61 +73,157 @@ func (mti MTI) HigherOrEqualThan(v MTI) bool {
 type origin int
 
 const (
-	OriginAcquirer       origin = iota //
-	OriginAcquirerRepeat               //
-	OriginIssuer                       //
-	OriginIssuerRepeat                 //
-	OriginOther                        //
-	OriginOtherRepeat                  //
-	OriginReservedByISO6               //
-	OriginReservedByISO7               //
-	OriginReservedByISO8               //
-	OriginReservedByISO9               //
+	// OriginAcquirer message type identifier.
+	OriginAcquirer origin = iota
+
+	// OriginAcquirerRepeat message type identifier.
+	OriginAcquirerRepeat
+
+	// OriginIssuer message type identifier.
+	OriginIssuer
+
+	// OriginIssuerRepeat message type identifier.
+	OriginIssuerRepeat
+
+	// OriginOther message type identifier.
+	OriginOther
+
+	// OriginOtherRepeat message type identifier.
+	OriginOtherRepeat
+
+	// OriginReservedByISO6 message type identifier.
+	OriginReservedByISO6
+
+	// OriginReservedByISO7 message type identifier.
+	OriginReservedByISO7
+
+	// OriginReservedByISO8 message type identifier.
+	OriginReservedByISO8
+
+	// OriginReservedByISO9 message type identifier.
+	OriginReservedByISO9
 )
 
 type function int
 
 const (
-	FunctionRequest                     function = iota * 10 // Request from acquirer to issuer to carry out an action; issuer may accept or reject
-	FunctionRequestResponse                                  // Issuer response to a request
-	FunctionAdvice                                           // Advice that an action has taken place; receiver can only accept, not reject
-	FunctionAdviceResponse                                   // Response to an advice
-	FunctionNotification                                     // Notification that an event has taken place; receiver can only accept, not reject
-	FunctionNotificationAcknowledgement                      // Response to a notification
-	FunctionInstruction                                      // ISO 8583:2003
-	FunctionInstructionAcknowledgement                       // Instruction acknowledgement
-	FunctionReservedByISO8                                   // Reserved for ISO.
-	FunctionReservedByISO9                                   // Reserved for ISO.
+	// FunctionRequest message type identifier.
+	// Request from acquirer to issuer to carry out an action; issuer may accept or reject
+	FunctionRequest function = iota * 10
+
+	// FunctionRequestResponse message type identifier.
+	// Issuer response to a request
+	FunctionRequestResponse
+
+	// FunctionAdvice message type identifier.
+	// Advice that an action has taken place; receiver can only accept, not reject
+	FunctionAdvice
+
+	// FunctionAdviceResponse message type identifier.
+	// Response to an advice
+	FunctionAdviceResponse
+
+	// FunctionNotification message type identifier.
+	// Notification that an event has taken place; receiver can only accept, not reject
+	FunctionNotification
+
+	// FunctionNotificationAcknowledgement message type identifier.
+	// Response to a notification
+	FunctionNotificationAcknowledgement
+
+	// FunctionInstruction message type identifier.
+	// ISO 8583:2003
+	FunctionInstruction
+
+	// FunctionInstructionAcknowledgement message type identifier.
+	// Instruction acknowledgement
+	FunctionInstructionAcknowledgement
+
+	// FunctionReservedByISO8 message type identifier.
+	// Reserved for ISO.
+	FunctionReservedByISO8
+
+	// FunctionReservedByISO9 message type identifier.
+	// Reserved for ISO.
+	FunctionReservedByISO9
 )
 
 type class int
 
 const (
-	ClassReservedByISO000              class = iota * 100 //
-	ClassAuthorizationMessage                             // Determine if funds are available, get an approval but do not post to account for reconciliation. Dual message system (DMS), awaits file exchange for posting to the account.
-	ClassFinancialMessages                                // Determine if funds are available, get an approval and post directly to the account. Single message system (SMS), no file exchange after this.
-	ClassFileActionsMessage                               // Used for hot-card, TMS and other exchanges
-	ClassReversalAndChargebackMessages                    // Reversal (x4x0 or x4x1): Reverses the action of a previous authorization. Chargeback (x4x2 or x4x3): Charges back a previously cleared financial message.
-	ClassReconciliationMessage                            // Transmits settlement information message.
-	ClassAdministrativeMessage                            // Transmits administrative advice. Often used for failure messages (e.g., message reject or failure to apply).
-	ClassFeeCollectionMessages                            //
-	ClassNetworkManagementMessage                         // Used for secure key exchange, logon, echo test and other network functions.
-	ClassReservedByISO900                                 //
+	// ClassReservedByISO000 message type identifier.
+	ClassReservedByISO000 class = iota * 100
+
+	// ClassAuthorizationMessage message type identifier.
+	// Determine if funds are available, get an approval but do not post to account for reconciliation.
+	// Dual message system (DMS), awaits file exchange for posting to the account.
+	ClassAuthorizationMessage
+
+	// ClassFinancialMessages message type identifier.
+	// Determine if funds are available, get an approval and post directly to the account. Single message system (SMS),
+	// no file exchange after this.
+	ClassFinancialMessages
+
+	// ClassFileActionsMessage message type identifier.
+	// Used for hot-card, TMS and other exchanges
+	ClassFileActionsMessage
+
+	// ClassReversalAndChargebackMessages message type identifier.
+	// Reversal (x4x0 or x4x1): Reverses the action of a previous authorization.
+	// Chargeback (x4x2 or x4x3): Charges back a previously cleared financial message.
+	ClassReversalAndChargebackMessages
+
+	// ClassReconciliationMessage message type identifier.
+	// Transmits settlement information message.
+	ClassReconciliationMessage
+
+	// ClassAdministrativeMessage message type identifier.
+	// Transmits administrative advice. Often used for failure messages (e.g., message reject or failure to apply).
+	ClassAdministrativeMessage
+
+	// ClassFeeCollectionMessages message type identifier.
+	ClassFeeCollectionMessages
+
+	// ClassNetworkManagementMessage message type identifier.
+	// Used for secure key exchange, logon, echo test and other network functions.
+	ClassNetworkManagementMessage
+
+	// ClassReservedByISO900 message type identifier.
+	ClassReservedByISO900
 )
 
 type version int
 
 const (
-	Version8583To1987        version = iota * 1000 //
-	Version8583To1993                              //
-	Version8583To2003                              //
-	VersionReservedByISO3000                       //
-	VersionReservedByISO4000                       //
-	VersionReservedByISO5000                       //
-	VersionReservedByISO6000                       //
-	VersionReservedByISO7000                       //
-	VersionNationalUse                             //
-	VersionPrivateUse                              //
+	// Version8583To1987 message type identifier.
+	Version8583To1987 version = iota * 1000
+
+	// Version8583To1993 message type identifier.
+	Version8583To1993
+
+	// Version8583To2003 message type identifier.
+	Version8583To2003
+
+	// VersionReservedByISO3000 message type identifier.
+	VersionReservedByISO3000
+
+	// VersionReservedByISO4000 message type identifier.
+	VersionReservedByISO4000
+
+	// VersionReservedByISO5000 message type identifier.
+	VersionReservedByISO5000
+
+	// VersionReservedByISO6000 message type identifier.
+	VersionReservedByISO6000
+
+	// VersionReservedByISO7000 message type identifier.
+	VersionReservedByISO7000
+
+	// VersionNationalUse message type identifier.
+	VersionNationalUse
+
+	// VersionPrivateUse message type identifier.
+	VersionPrivateUse
 )
 
 func itoa(n int) string { return strconv.Itoa(n) }

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ type entry struct {`
`14`	`14`	`representation rune`
`15`	`15`	`}`
`16`	`16`
	`17`	`+// NULL is used for invalid encoding conversions.`
`17`	`18`	`const NULL = 0x0`
`18`	`19`
`19`	`20`	`// FromGoString converts a string to ebcdic bytes.`
`@@ -37,7 +38,7 @@ func (v *version) FromGoString(s string) []byte {`
`37`	`38`	`return output`
`38`	`39`	`}`
`39`	`40`
`40`		`-// FromGoString converts a ebcdic bytes to a string.`
	`41`	`+// ToGoString converts a ebcdic bytes to a string.`
`41`	`42`	`func (v *version) ToGoString(b []byte) string {`
`42`	`43`	`if len(v.decoding) == 0 {`
`43`	`44`	`v.generateDecodingMap()`
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ func (b BITMAP) MarshalISO8583(length int, encoding string) ([]byte, error) {`
`31`	`31`	`return bitmap.ToBytes(b.Bitmap), nil`
`32`	`32`	`}`
`33`	`33`
`34`		`-// Returns which bits are on, key values are between 1 and 64, both included.`
	`34`	`+// Bits returns which bits are on, key values are between 1 and 64, both included.`
`35`	`35`	`// First value is bit 1.`
`36`	`36`	`func (b BITMAP) Bits() (map[int]bool, error) {`
`37`	`37`	`return b.Bitmap, nil`
Original file line number	Diff line number	Diff line change
`@@ -4,11 +4,13 @@ import (`
`4`	`4`	`"github.com/jattento/go-iso8583/pkg/encoding/ebcdic"`
`5`	`5`	`)`
`6`	`6`
	`7`	`+// UnmarshalDecodings is the unmarshal encodings map used by inbuilt ISO fields, you can append more encoding for extended functionality.`
`7`	`8`	`var UnmarshalDecodings = map[string]func([]byte) ([]byte, error){`
`8`	`9`	`"ebcdic": errWrapper(func(bytes []byte) []byte { return []byte(ebcdic.V1047.ToGoString(bytes)) }),`
`9`	`10`	`"ascii": nop,`
`10`	`11`	`}`
`11`	`12`
	`13`	`+// MarshalEncodings is the marshal encodings map used by inbuilt ISO fields, you can append more encoding for extended functionality.`
`12`	`14`	`var MarshalEncodings = map[string]func([]byte) ([]byte, error){`
`13`	`15`	`"ebcdic": errWrapper(func(bytes []byte) []byte {`
`14`	`16`	`return ebcdic.V1047.FromGoString(string(bytes))`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,8 @@ import (`
`4`	`4`	`"errors"`
`5`	`5`	`)`
`6`	`6`
`7`		`-// LLLVAR: For use of different encoding for 'LLL' and 'VAR' separate both encodings with a slash,`
	`7`	`+// LLLVAR field type.`
	`8`	`+// For use of different encoding for 'LLL' and 'VAR' separate both encodings with a slash,`
`8`	`9`	`// where first element is the lll encoding and the second the var encoding.`
`9`	`10`	`// For Unmarshal length indicate the amount of byte that contain the LLL value`
`10`	`11`	`// For example:`
Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,8 @@ import (`
`8`	`8`	`"unicode"`
`9`	`9`	`)`
`10`	`10`
`11`		`-// LLVAR: For use of different encoding for 'LL' and 'VAR' separate both encodings with a slash,`
	`11`	`+// LLVAR field type.`
	`12`	`+// For use of different encoding for 'LL' and 'VAR' separate both encodings with a slash,`
`12`	`13`	`// where first element is the ll encoding and the second the var encoding.`
`13`	`14`	`// For Unmarshal length indicate the amount of byte that contain the LL value`
`14`	`15`	`// For example:`