Better comments and fix broken test.

Author: markt-asf

java/org/apache/tomcat/buildutil/translate/Utils.java

@@ -71,6 +71,14 @@ static Properties load(File f) {
     }
 
 
+    /*
+     * This is the formatting applied when exporting values from Tomcat to POE.
+     *
+     * The values have been read from Tomcat's property files (so the input is the actual value with none of the
+     * escaping required to represent that value in a property file) and are being written back out in a single file to
+     * be imported into POEditor. The padding for blank lines needs to be added followed by the common formatting
+     * required to convert a property value to the representation of that value in a file.
+     */
     static String formatValueExport(String in) {
         String result;
 
@@ -84,6 +92,14 @@ static String formatValueExport(String in) {
     }
 
 
+    /*
+     * This is the formatting applied when importing values to Tomcat from POE.
+     *
+     * The values have been read from POE's property files (so the input is the actual value with none of the
+     * escaping required to represent that value in a property file) and are being written back out to individual files
+     * in Tomcat. The padding for blank lines needs to be removed followed by the common formatting required to convert
+     * a property value to the representation of that value in a file.
+     */
     static String formatValueImport(String in) {
         String result;
 
@@ -111,7 +127,13 @@ static String fixUnnecessaryEscaping(String key, String value) {
 
 
     /*
-     * Common formatting to convert a String for storage as a value in a property file.
+     * Common formatting to convert a String value for storage as a value in a property file. Values that contain
+     * line-breaks need the line-break in the value to be replaced with the correct representation of a line-break in a
+     * property file. Leading space needs to be escaped with a '\' and horizontal tabs need to be converted to "\t".
+     *
+     * Note that a single '\' needs to be escaped both in a Java string and in a property file so if a property value
+     * needs to contain a single `\` (e.g. to escape white space at the start of a line) that will appear as "\\\\" in
+     * the Java code.
      */
     static String formatValueCommon(String in) {
         String result = in.replace("\n", "\\n\\\n");

test/org/apache/tomcat/buildutil/translate/TestUtils.java

@@ -23,30 +23,36 @@ public class TestUtils {
 
     @Test
     public void testFormatValue01() {
-        // Import from Tomcat
-        Assert.assertEquals("\\n\\\n</web-fragment>\\n", Utils.formatValueImport("\\n\\\n</web-fragment>\\n"));
+        // Import from POE
+        Assert.assertEquals("line1\\n\\\nline2\\n\\\nline3", Utils.formatValueImport("line1\nline2\nline3"));
     }
 
     @Test
     public void testFormatValue02() {
-        // Import from POEditor
-        Assert.assertEquals("\\n\\\n</web-fragment>\\n", Utils.formatValueImport("\\n</web-fragment>\\n"));
+        // Import from POE
+        Assert.assertEquals("\\n\\\nline2\\n\\\nline3", Utils.formatValueImport(Utils.PADDING + "\nline2\nline3"));
     }
 
     @Test
     public void testFormatValue03() {
+        // Import from POE
+        Assert.assertEquals("line1\\n\\\n\\tline2\\n\\\n\\tline3", Utils.formatValueImport("line1\n\tline2\n\tline3"));
+    }
+
+    @Test
+    public void testFormatValue04() {
         // Export from Tomcat
         Assert.assertEquals("line1\\n\\\nline2\\n\\\nline3", Utils.formatValueExport("line1\nline2\nline3"));
     }
 
     @Test
-    public void testFormatValue04() {
+    public void testFormatValue05() {
         // Export from Tomcat
         Assert.assertEquals(Utils.PADDING + "\\n\\\nline2\\n\\\nline3", Utils.formatValueExport("\nline2\nline3"));
     }
 
     @Test
-    public void testFormatValue05() {
+    public void testFormatValue06() {
         // Export from Tomcat
         Assert.assertEquals("line1\\n\\\n\\tline2\\n\\\n\\tline3", Utils.formatValueExport("line1\n\tline2\n\tline3"));
     }