From ad8f8731b6fda414c21f263c541c27854d64d851 Mon Sep 17 00:00:00 2001
From: Tim Hockin <thockin@google.com>
Date: Fri, 10 Jul 2015 21:50:56 -0700
Subject: [PATCH] Use a common set of tag prefixes for munges

All munges now start with `<!-- BEGIN MUNGE:` and end with `<!-- END MUNGE:`.
This lets me (in a followup) filter them better to normalize contents during
verification of generated docs.
---
 cmd/mungedocs/toc.go                 |  6 ++++--
 cmd/mungedocs/toc_test.go            | 18 ++++++++++++------
 cmd/mungedocs/unversioned_warning.go |  9 ++++++---
 cmd/mungedocs/util.go                | 12 ++++++++++++
 docs/networking.md                   |  4 ++--
 5 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/cmd/mungedocs/toc.go b/cmd/mungedocs/toc.go
index 9011e117db9..de0bdca6ecb 100644
--- a/cmd/mungedocs/toc.go
+++ b/cmd/mungedocs/toc.go
@@ -23,10 +23,12 @@ import (
 	"strings"
 )
 
+const tocMungeTag = "GENERATED_TOC"
+
 // inserts/updates a table of contents in markdown file.
 //
 // First, builds a ToC.
-// Then, finds <!-- BEGIN GENERATED TOC --> and <!-- END GENERATED TOC -->, and replaces anything between those with
+// Then, finds the magic macro block tags and replaces anything between those with
 // the ToC, thereby updating any previously inserted ToC.
 //
 // TODO(erictune): put this in own package with tests
@@ -36,7 +38,7 @@ func updateTOC(filePath string, markdown []byte) ([]byte, error) {
 		return nil, err
 	}
 	lines := splitLines(markdown)
-	updatedMarkdown, err := updateMacroBlock(lines, "<!-- BEGIN GENERATED TOC -->", "<!-- END GENERATED TOC -->", string(toc))
+	updatedMarkdown, err := updateMacroBlock(lines, beginMungeTag(tocMungeTag), endMungeTag(tocMungeTag), string(toc))
 	if err != nil {
 		return nil, err
 	}
diff --git a/cmd/mungedocs/toc_test.go b/cmd/mungedocs/toc_test.go
index 5175d8089f1..4875d93c049 100644
--- a/cmd/mungedocs/toc_test.go
+++ b/cmd/mungedocs/toc_test.go
@@ -29,8 +29,10 @@ func Test_buildTOC(t *testing.T) {
 	}{
 		{"", ""},
 		{"Lorem ipsum\ndolor sit amet\n", ""},
-		{"# Title\nLorem ipsum \n## Section Heading\ndolor sit amet\n",
-			"- [Title](#title)\n  - [Section Heading](#section-heading)\n"},
+		{
+			"# Title\nLorem ipsum \n## Section Heading\ndolor sit amet\n",
+			"- [Title](#title)\n  - [Section Heading](#section-heading)\n",
+		},
 	}
 	for _, c := range cases {
 		actual, err := buildTOC([]byte(c.in))
@@ -47,10 +49,14 @@ func Test_updateTOC(t *testing.T) {
 		out string
 	}{
 		{"", ""},
-		{"Lorem ipsum\ndolor sit amet\n",
-			"Lorem ipsum\ndolor sit amet\n"},
-		{"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN GENERATED TOC -->\nold cruft\n<!-- END GENERATED TOC -->\n## Section Heading\ndolor sit amet\n",
-			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN GENERATED TOC -->\n- [Title](#title)\n  - [Section Heading](#section-heading)\n\n<!-- END GENERATED TOC -->\n## Section Heading\ndolor sit amet\n"},
+		{
+			"Lorem ipsum\ndolor sit amet\n",
+			"Lorem ipsum\ndolor sit amet\n",
+		},
+		{
+			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN MUNGE: GENERATED_TOC -->\nold cruft\n<!-- END MUNGE: GENERATED_TOC -->\n## Section Heading\ndolor sit amet\n",
+			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN MUNGE: GENERATED_TOC -->\n- [Title](#title)\n  - [Section Heading](#section-heading)\n\n<!-- END MUNGE: GENERATED_TOC -->\n## Section Heading\ndolor sit amet\n",
+		},
 	}
 	for _, c := range cases {
 		actual, err := updateTOC("filename.md", []byte(c.in))
diff --git a/cmd/mungedocs/unversioned_warning.go b/cmd/mungedocs/unversioned_warning.go
index 8939fce4532..7768fe38a95 100644
--- a/cmd/mungedocs/unversioned_warning.go
+++ b/cmd/mungedocs/unversioned_warning.go
@@ -16,9 +16,12 @@ limitations under the License.
 
 package main
 
-var beginUnversionedWarning = "<!-- BEGIN UNVERSIONED_WARNING -->"
-var endUnversionedWarning = "<!-- END UNVERSIONED_WARNING -->"
-var unversionedWarning = `
+const unversionedWarningTag = "UNVERSIONED_WARNING"
+
+var beginUnversionedWarning = beginMungeTag(unversionedWarningTag)
+var endUnversionedWarning = endMungeTag(unversionedWarningTag)
+
+const unversionedWarning = `
 <!-- BEGIN STRIP_FOR_RELEASE -->
 
 <h1>*** PLEASE NOTE: This document applies to the HEAD of the source
diff --git a/cmd/mungedocs/util.go b/cmd/mungedocs/util.go
index 8581f5152b9..d4e9773f677 100644
--- a/cmd/mungedocs/util.go
+++ b/cmd/mungedocs/util.go
@@ -98,3 +98,15 @@ func hasMacroBlock(lines []string, begin string, end string) bool {
 	}
 	return false
 }
+
+// Returns the canonical begin-tag for a given description.  This does not
+// include the trailing newline.
+func beginMungeTag(desc string) string {
+	return fmt.Sprintf("<!-- BEGIN MUNGE: %s -->", desc)
+}
+
+// Returns the canonical end-tag for a given description.  This does not
+// include the trailing newline.
+func endMungeTag(desc string) string {
+	return fmt.Sprintf("<!-- END MUNGE: %s -->", desc)
+}
diff --git a/docs/networking.md b/docs/networking.md
index d9f439c0843..d91081e5f2b 100644
--- a/docs/networking.md
+++ b/docs/networking.md
@@ -1,6 +1,6 @@
 # Networking in Kubernetes
 **Table of Contents**
-<!-- BEGIN GENERATED TOC -->
+<!-- BEGIN MUNGE: GENERATED_TOC -->
 - [Networking in Kubernetes](#networking-in-kubernetes)
   - [Summary](#summary)
   - [Docker model](#docker-model)
@@ -14,7 +14,7 @@
     - [Calico](#calico)
   - [Other reading](#other-reading)
 
-<!-- END GENERATED TOC -->
+<!-- END MUNGE: GENERATED_TOC -->
 
 Kubernetes approaches networking somewhat differently than Docker does by
 default.  There are 4 distinct networking problems to solve: