Fix missing comments on exported functions

Add comments to exported functions that were still missing any documentation.

pkg/v1/ytbx/errors.go

@@ -25,6 +25,8 @@ import (
 	"strings"
 )
 
+// KeyNotFoundInMapError represents an error when a key in a map was expected,
+// but could not be found.
 type KeyNotFoundInMapError struct {
 	MissingKey    string
 	AvailableKeys []string
@@ -36,13 +38,17 @@ func (e *KeyNotFoundInMapError) Error() string {
 		strings.Join(e.AvailableKeys, ", "))
 }
 
+// NoNamedEntryListError represents the situation where a list was expected to
+// be a named-entry list, but one or more entries were not maps.
 type NoNamedEntryListError struct {
 }
 
 func (e *NoNamedEntryListError) Error() string {
 	return "not a named-entry list, one or more entries are not of type map"
 }
 
+// InvalidPathString represents the error that a path string is not a valid
+// Dot-style or GoPatch path syntax and does not match a provided document.
 type InvalidPathString struct {
 	Style       PathStyle
 	PathString  string

pkg/v1/ytbx/path.go

@@ -28,18 +28,33 @@ import (
 	yaml "gopkg.in/yaml.v2"
 )
 
+// PathStyle is a custom type for supported path styles
 type PathStyle int
 
+// Supported styles are the Dot-Style (used by Spruce for example) and GoPatch
+// Style which is used by BOSH
 const (
 	DotStyle PathStyle = iota
 	GoPatchStyle
 )
 
+// Path points to a section in a data struture by using names to identify the
+// location.
+// Example:
+//   ---
+//   sizing:
+//     api:
+//       count: 2
+// For example, `sizing.api.count` points to the key `sizing` of the root
+// element and in there to the key `api` and so on and so forth.
 type Path struct {
 	DocumentIdx  int
 	PathElements []PathElement
 }
 
+// PathElement represents one part of a path, which can either address an entry
+// in a map (by name), a named-entry list entry (key and name), or an entry in a
+// list (by index).
 type PathElement struct {
 	Idx  int
 	Key  string
@@ -50,6 +65,7 @@ func (path Path) String() string {
 	return path.ToGoPatchStyle()
 }
 
+// ToGoPatchStyle returns the path as a GoPatch style string.
 func (path *Path) ToGoPatchStyle() string {
 	sections := []string{""}
 
@@ -69,6 +85,7 @@ func (path *Path) ToGoPatchStyle() string {
 	return strings.Join(sections, "/")
 }
 
+// ToDotStyle returns the path as a Dot-Style string.
 func (path *Path) ToDotStyle() string {
 	sections := []string{}
 
@@ -85,6 +102,8 @@ func (path *Path) ToDotStyle() string {
 	return strings.Join(sections, ".")
 }
 
+// NewPathWithPathElement returns a new path based on a given path adding a new
+// path element.
 func NewPathWithPathElement(path Path, pathElement PathElement) Path {
 	result := make([]PathElement, len(path.PathElements))
 	copy(result, path.PathElements)
@@ -94,25 +113,33 @@ func NewPathWithPathElement(path Path, pathElement PathElement) Path {
 		PathElements: append(result, pathElement)}
 }
 
+// NewPathWithNamedElement returns a new path based on a given path adding a new
+// of type entry in map using the name.
 func NewPathWithNamedElement(path Path, name interface{}) Path {
 	return NewPathWithPathElement(path, PathElement{
 		Idx:  -1,
 		Name: fmt.Sprintf("%v", name)})
 }
 
+// NewPathWithNamedListElement returns a new path based on a given path adding a
+// new of type entry in a named-entry list by using key and name.
 func NewPathWithNamedListElement(path Path, identifier interface{}, name interface{}) Path {
 	return NewPathWithPathElement(path, PathElement{
 		Idx:  -1,
 		Key:  fmt.Sprintf("%v", identifier),
 		Name: fmt.Sprintf("%v", name)})
 }
 
+// NewPathWithIndexedListElement returns a new path based on a given path adding
+// a new of type list entry using the index.
 func NewPathWithIndexedListElement(path Path, idx int) Path {
 	return NewPathWithPathElement(path, PathElement{
 		Idx: idx,
 	})
 }
 
+// ListPaths returns all paths in the documents using the provided choice of
+// path style.
 func ListPaths(location string, style PathStyle) ([]Path, error) {
 	inputfile, err := LoadFile(location)
 	if err != nil {
@@ -156,6 +183,8 @@ func traverseTree(path Path, obj interface{}, leafFunc func(path Path, value int
 	}
 }
 
+// ParseGoPatchStylePathString returns a path by parsing a string representation
+// which is assumed to be a GoPatch style path.
 func ParseGoPatchStylePathString(path string) (Path, error) {
 	elements := make([]PathElement, 0)
 
@@ -189,6 +218,8 @@ func ParseGoPatchStylePathString(path string) (Path, error) {
 	return Path{DocumentIdx: 0, PathElements: elements}, nil
 }
 
+// ParseDotStylePathString returns a path by parsing a string representation
+// which is assumed to be a Dot-Style path.
 func ParseDotStylePathString(path string, obj interface{}) (Path, error) {
 	elements := make([]PathElement, 0)
 
@@ -255,6 +286,8 @@ func ParseDotStylePathString(path string, obj interface{}) (Path, error) {
 	return Path{DocumentIdx: 0, PathElements: elements}, nil
 }
 
+// ParsePathString returns a path by parsing a string representation
+// of a path, which can be one of the supported types.
 func ParsePathString(pathString string, obj interface{}) (Path, error) {
 	if IsDotStylePath(pathString) {
 		return ParseDotStylePathString(pathString, obj)
@@ -263,6 +296,7 @@ func ParsePathString(pathString string, obj interface{}) (Path, error) {
 	return ParseGoPatchStylePathString(pathString)
 }
 
+// IsDotStylePath checks whether the path string is a Dot-Style path.
 func IsDotStylePath(pathString string) bool {
 	return !strings.HasPrefix(pathString, "/")
 }

pkg/v1/ytbx/path_test.go

@@ -36,7 +36,7 @@ func getExampleDocument() interface{} {
 }
 
 var _ = Describe("path tests", func() {
-	Context("parse dot style path strings into a path", func() {
+	Context("parse dot-style path strings into a path", func() {
 		It("should parse string with only map elements", func() {
 			path, err := ParseDotStylePathString("yaml.structure.somekey", getExampleDocument())
 			Expect(err).To(BeNil())