From e24259f1a36dd5ecc2bfbd0caafd1282a9c69597 Mon Sep 17 00:00:00 2001
From: Paul Hoadley <paulh@logicsquad.net>
Date: Thu, 3 Jan 2013 15:52:44 +1030
Subject: [PATCH] Improves Javadoc comments.

Basically this makes the class-level Javadoc comment legible: raw tags
and entities obviously get eaten on rendering to HTML. Some
method-level clean-up. Added a note about the component's use of
escapeHTML=false in its WOString.
---
 .../components/ERXStringWithLineBreaks.java   | 84 +++++++++++--------
 1 file changed, 50 insertions(+), 34 deletions(-)

diff --git a/Frameworks/Core/ERExtensions/Sources/er/extensions/components/ERXStringWithLineBreaks.java b/Frameworks/Core/ERExtensions/Sources/er/extensions/components/ERXStringWithLineBreaks.java
index 43adcafbdc2..0ea78dbbd26 100644
--- a/Frameworks/Core/ERExtensions/Sources/er/extensions/components/ERXStringWithLineBreaks.java
+++ b/Frameworks/Core/ERExtensions/Sources/er/extensions/components/ERXStringWithLineBreaks.java
@@ -12,17 +12,24 @@
 import er.extensions.foundation.ERXStringUtilities;
 
 /**
- * Simple component that can convert a string that has
- * line breaks and tabs in it into an html string that
- * has <BR> and &nbsp instead. Very useful for preserving
- * line breaks that are typed into a WOTextBox.
- * <br/>
- * Synopsis:<br/>
+ * <p>
+ * Converts a string that has line breaks and tabs in it into a corresponding
+ * HTML string with <code>&lt;br /&gt;</code> and (five of)
+ * <code>&amp;nbsp;</code> instead. Useful, for example, for preserving line
+ * breaks that are typed into a {@code WOTextBox}. Note that this component
+ * renders its output via a {@code WOString} element with
+ * {@code escapeHTML=false}, which is a security risk if the value being
+ * rendered comes from an untrusted source.
+ * </p>
+ * 
+ * <h3>Synopsis</h3>
+ * <p>
  * value=<i>aString</i>;[valueWhenEmpty=<i>aString</i>;]
+ * </p>
  * 
  * @binding value string to be converted
- * @binding valueWhenEmpty if null or length of zero what to
- *		display
+ * @binding valueWhenEmpty what to display when <code>value</code> is null or
+ *          empty
  */
 public class ERXStringWithLineBreaks extends ERXStatelessComponent {
 	/**
@@ -32,30 +39,36 @@ public class ERXStringWithLineBreaks extends ERXStatelessComponent {
 	 */
 	private static final long serialVersionUID = 1L;
 
-    /** holds the html-ified string */
+	/**
+	 * Holds the HTML-ified string
+	 */
     public String _value;
 
-    /**
-     * Public constructor
-     * @param context current context
-     */
+	/**
+	 * Constructor
+	 * 
+	 * @param context
+	 *            current context
+	 */
     public ERXStringWithLineBreaks(WOContext context) {
         super(context);
     }
     
-    /**
-     * Nulls out cached instance variable: _value
-     */
+	/**
+	 * Nulls out cached instance variable: _value
+	 */
     public void reset() {
         super.reset();
         _value = null;
     }
-    /**
-        * Converts '\r\n', '\n', '\r' into "&lt;br /&gt;" and
-     * converts '\t' into five non-breaking spaces.
-     * @return converts string bound to binding: <b>value</b>
-     * 		into html-ified line breaks.
-     */
+
+	/**
+	 * Converts '<code>\r\n</code>', '<code>\n</code>', '<code>\r</code>' into '
+	 * <code>&lt;br /&gt;</code>' and converts '<code>\t</code>' into five
+	 * non-breaking spaces.
+	 * 
+	 * @return converted string
+	 */
     // FIXME: Should use ERXSimpleHTMLFormatter
     public String value() {
         if (_value == null) {
@@ -79,11 +92,13 @@ protected String valueToString(Object value) {
         return result;
     }
     
-    /**
-     * Set the value to be displayed.<br />
-     * This is useful when you want to return a string from a DirectAction for example for debugging purposes.
-     * @param newValue Object to display
-     */
+	/**
+	 * Sets the value to be displayed. This is useful when you want to return a
+	 * string from a DirectAction, for example, for debugging purposes.
+	 * 
+	 * @param newValue
+	 *            Object to display
+	 */
     public void setValue(Object newValue) {
         if(newValue != null) {
             _value = valueToString(newValue);
@@ -98,11 +113,12 @@ public String tabs() {
         return "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;";
     }
     
-    /**
-     * Returns binding <b>valueWhenEmpty</b>.
-     * @return value to display when the string is empty
-     */
-    public Object valueWhenEmpty() {
-        return valueToString(objectValueForBinding("valueWhenEmpty"));
-    }
+	/**
+	 * Returns binding {@code valueWhenEmpty}.
+	 * 
+	 * @return value to display when the string is empty
+	 */
+	public Object valueWhenEmpty() {
+		return valueToString(objectValueForBinding("valueWhenEmpty"));
+	}
 }