WIP -- a sketch of something working; some tests are broken

pkg/workspace/comment_post_processing.go

@@ -0,0 +1,48 @@
+// Copyright 2020 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package workspace
+
+import (
+	"github.com/vmware-tanzu/carvel-ytt/pkg/filepos"
+	"github.com/vmware-tanzu/carvel-ytt/pkg/template"
+	"github.com/vmware-tanzu/carvel-ytt/pkg/yamlmeta"
+	"github.com/vmware-tanzu/carvel-ytt/pkg/yamltemplate"
+)
+
+// CommentPostProcessing is an instance of the process of filling in templated comments into the configured document
+// set.
+type CommentPostProcessing struct {
+	docSets map[*FileInLibrary]*yamlmeta.DocumentSet
+}
+
+// Visit converts annotated comments into YAML comments
+func (o CommentPostProcessing) Visit(node yamlmeta.Node) error {
+	comments := []*yamlmeta.Comment{}
+	anns := template.NewAnnotations(node)
+	if anns.Has(yamltemplate.AnnotationHeadComment) {
+		comments = append(comments, &yamlmeta.Comment{
+			Data:     anns.Args(yamltemplate.AnnotationHeadComment)[0].String(),
+			Position: filepos.NewUnknownPosition(),
+		})
+	}
+	if anns.Has(yamltemplate.AnnotationLineComment) {
+		comments = append(comments, &yamlmeta.Comment{
+			Data:     anns.Args(yamltemplate.AnnotationLineComment)[0].String(),
+			Position: node.GetPosition(),
+		})
+	}
+	node.SetComments(comments)
+	return nil
+}
+
+// Apply performs comment post-processing on the configured document set.
+func (o CommentPostProcessing) Apply() (map[*FileInLibrary]*yamlmeta.DocumentSet, error) {
+	for _, docSet := range o.docSets {
+		err := yamlmeta.Walk(docSet, o)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return o.docSets, nil
+}

pkg/workspace/library_execution.go

@@ -164,6 +164,11 @@ func (ll *LibraryExecution) Eval(values *datavalues.Envelope, libraryValues []*d
 		return nil, err
 	}
 
+	docSets, err = (&CommentPostProcessing{docSets: docSets}).Apply()
+	if err != nil {
+		return nil, err
+	}
+
 	result := &EvalResult{
 		Files:   outputFiles,
 		DocSet:  &yamlmeta.DocumentSet{},

pkg/yamlmeta/convert.go

@@ -32,18 +32,21 @@ func NewGoFromAST(val interface{}) interface{} {
 func convertToYAML3Node(val interface{}) *yaml3.Node {
 	switch typedVal := val.(type) {
 	case *Document:
-		// head, inline := convertYAML3Comments(typedVal)
+		head, inline := convertYAML3Comments(typedVal)
 		return &yaml3.Node{
-			Kind:    yaml3.DocumentNode,
-			Content: []*yaml3.Node{convertToYAML3Node(typedVal.Value)},
-			// HeadComment: head.String(),
-			// LineComment: inline.String(),
+			Kind:        yaml3.DocumentNode,
+			Content:     []*yaml3.Node{convertToYAML3Node(typedVal.Value)},
+			HeadComment: head,
+			LineComment: inline,
 		}
 	case *Map:
 		yamlMap := &yaml3.Node{Kind: yaml3.MappingNode}
 		for _, item := range typedVal.Items {
 			key := convertToYAML3Node(item.Key)
 			value := convertToYAML3Node(item.Value)
+			head, inline := convertYAML3Comments(item)
+			key.HeadComment = head
+			key.LineComment = inline
 			yamlMap.Content = append(yamlMap.Content, key, value)
 		}
 		return yamlMap
@@ -58,7 +61,11 @@ func convertToYAML3Node(val interface{}) *yaml3.Node {
 	case *Array:
 		yamlArray := &yaml3.Node{Kind: yaml3.SequenceNode}
 		for _, item := range typedVal.Items {
-			yamlArray.Content = append(yamlArray.Content, convertToYAML3Node(item.Value))
+			yamlItem := convertToYAML3Node(item.Value)
+			head, inline := convertYAML3Comments(item)
+			yamlItem.HeadComment = head
+			yamlItem.LineComment = inline
+			yamlArray.Content = append(yamlArray.Content, yamlItem)
 		}
 		return yamlArray
 	case []interface{}:
@@ -78,25 +85,28 @@ func convertToYAML3Node(val interface{}) *yaml3.Node {
 	case string:
 		if val == "" {
 			return &yaml3.Node{Kind: yaml3.ScalarNode, Value: "", Style: yaml3.DoubleQuotedStyle}
-		} else {
-			return &yaml3.Node{Kind: yaml3.ScalarNode, Value: fmt.Sprintf("%s", val), Tag: "!!str"}
 		}
+		return &yaml3.Node{Kind: yaml3.ScalarNode, Value: fmt.Sprintf("%s", val), Tag: "!!str"}
 	default:
 		panic(fmt.Sprintf("Unexpected type %T = %#v", val, val))
 	}
 }
 
-func convertYAML3Comments(typedVal Node) (strings.Builder, strings.Builder) {
+func convertYAML3Comments(typedVal Node) (string, string) {
 	head := strings.Builder{}
 	inline := strings.Builder{}
 	for _, comment := range typedVal.GetComments() {
-		if comment.Position.IsNextTo(typedVal.GetPosition()) {
-			inline.WriteString(comment.Data)
+		if comment.Position.LineNum() == typedVal.GetPosition().LineNum() {
+			// yaml.v3 prepends a space to comments that do _not_ begin with an octothorpe
+			if inline.Len() == 0 {
+				inline.WriteString("#")
+			}
+			inline.WriteString(comment.Data + " ")
 		} else {
-			head.WriteString(comment.Data)
+			head.WriteString("#" + comment.Data + "\n")
 		}
 	}
-	return head, inline
+	return head.String(), inline.String()
 }
 
 func convertToLowYAML(val interface{}) interface{} {

pkg/yamlmeta/document.go

@@ -25,20 +25,14 @@ func (d *Document) IsEmpty() bool {
 
 func (d *Document) AsYAMLBytes() ([]byte, error) {
 	out := bytes.Buffer{}
-	// TODO: re-enable including comments after all tests are verified working, as is.
-	// if len(d.Comments) > 0 {
-	// 	for _, comment := range d.Comments {
-	// 		out.WriteString(fmt.Sprintf("#%s\n", comment.Data))
-	// 	}
-	// 	out.WriteString("---\n")
-	// }
 
 	encoder := yaml3.NewEncoder(&out)
 	encoder.SetIndent(2)
 	err := encoder.Encode(convertToYAML3Node(d))
 	if err != nil {
 		return nil, err
 	}
+
 	return out.Bytes(), nil
 }
 

pkg/yamltemplate/comments.go

@@ -0,0 +1,13 @@
+// Copyright 2020 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package yamltemplate
+
+import "github.com/vmware-tanzu/carvel-ytt/pkg/template"
+
+// Comment annotation names
+const (
+	AnnotationYAMLComment template.AnnotationName = "yaml/comment"
+	AnnotationHeadComment template.AnnotationName = "yaml/head-comment"
+	AnnotationLineComment template.AnnotationName = "yaml/line-comment"
+)

pkg/yamltemplate/filetests/templated-string.tpltest

@@ -19,6 +19,7 @@ metadata:
       fromyaml=(@= yamlfunc() @)
       fromtext=(@= textfunc() @)
 
+#@yaml/comment "Hello, world"
 #@yaml/text-templated-strings
 #@yaml/map-key-override
 ---

pkg/yamltemplate/metas.go

@@ -62,6 +62,17 @@ func NewTemplateAnnotationFromYAMLComment(comment *yamlmeta.Comment, nodePos *fi
 		}
 	}
 
+	// Allow author to place comments above (head) and inline (line) the node.
+	if ann.Name == AnnotationYAMLComment {
+		ann.Name = AnnotationHeadComment
+
+		if nodePos.IsKnown() {
+			if comment.Position.LineNum() == nodePos.LineNum() {
+				ann.Name = AnnotationLineComment
+			}
+		}
+	}
+
 	return ann, nil
 }