Apply suggestions from code review

Co-authored-by: Lucas Käldström <luxas@users.noreply.github.com>

marshal.go

@@ -7,7 +7,11 @@ import (
 	"gopkg.in/yaml.v2"
 )
 
-// JSONToYAML Converts JSON to YAML.
+// JSONToYAML converts JSON to YAML. Notable implementation details:
+//
+//  - Duplicate fields, are case-sensitively ignored in an undefined order.
+//  - The sequence indentation style is compact, which means that the "- " marker for a YAML sequence will be on the same indentation level as the sequence field name.
+//  - Unlike Unmarshal, all integers, up to 64 bits, are preserved during this round-trip.
 func JSONToYAML(j []byte) ([]byte, error) {
 	// Convert the JSON to an object.
 	var jsonObj interface{}
@@ -31,8 +35,7 @@ func JSONToYAML(j []byte) ([]byte, error) {
 	return yamlBytes, nil
 }
 
-// Marshal marshals the object into JSON then converts JSON to YAML and returns the
-// YAML.
+// Marshal marshals obj into JSON using stdlib json.Marshal, and then converts JSON to YAML using JSONToYAML (see that method for more reference)
 func Marshal(obj interface{}) ([]byte, error) {
 	jsonBytes, err := json.Marshal(obj)
 	if err != nil {

unmarshal.go

@@ -97,14 +97,26 @@ func unmarshal(yamlBytes []byte, obj interface{}, unmarshalFn func([]byte, inter
 	return nil
 }
 
-// Unmarshal converts YAML to JSON then uses JSON to unmarshal into an object,
-// optionally configuring the behavior of the JSON unmarshal.
+// Unmarshal first converts the given YAML to JSON, and then unmarshals the JSON into obj. Options for the
+// standard library json.Decoder can be optionally specified, e.g. to decode untyped numbers into json.Number instead of float64, or to disallow unknown fields (but for that purpose, see also UnmarshalStrict). obj must be a non-nil pointer.
+//
+// Important notes about the Unmarshal logic:
+//
+//  - Decoding is case-insensitive, unlike the rest of Kubernetes API machinery, as this is using the stdlib json library. This might be confusing to users.
+//  - This decodes any number (although it is an integer) into a float64 if the type of obj is unknown, e.g. *map[string]interface{}, *interface{}, or *[]interface{}. This means integers above +/- 2^53 will lose precision when round-tripping. Make a JSONOpt that calls d.UseNumber() to avoid this.
+//  - Duplicate fields, including in-case-sensitive matches, are ignored in an undefined order. Note that the YAML specification forbids duplicate fields, so this logic is more permissive than it needs to. See UnmarshalStrict for an alternative.
+//  - Unknown fields, i.e. serialized data that do not map to a field in obj, are ignored. Use d.DisallowUnknownFields() or UnmarshalStrict to override.
+//  - As per the YAML 1.1 specification, which yaml.v2 used underneath implements, literal 'yes' and 'no' strings without quotation marks will be converted to true/false implicitly.
+//  - YAML non-string keys, e.g. ints, bools and floats, are converted to strings implicitly during the YAML to JSON conversion process.
+//  - There are no compatibility guarantees for returned error values.
 func Unmarshal(yamlBytes []byte, obj interface{}, opts ...JSONOpt) error {
 	return unmarshal(yamlBytes, obj, yaml.Unmarshal, opts...)
 }
 
-// UnmarshalStrict strictly converts YAML to JSON then uses JSON to unmarshal
-// into an object, optionally configuring the behavior of the JSON unmarshal.
+// UnmarshalStrict is similar to Unmarshal (please read its documentation for reference), with the following exceptions:
+//
+//  - Duplicate fields in an object yield an error. This is according to the YAML specification.
+//  - If obj, or any of its recursive children, is a struct, presence of fields in the serialized data unknown to the struct will yield an error.
 func UnmarshalStrict(yamlBytes []byte, obj interface{}, opts ...JSONOpt) error {
 	return unmarshal(yamlBytes, obj, yaml.UnmarshalStrict, append(opts, DisallowUnknownFields)...)
 }