--- a/ChangeLog	Wed Sep 18 16:09:51 2013 +0200
+++ b/ChangeLog	Thu Sep 19 11:06:09 2013 +0200
@@ -1,3 +1,8 @@
+2013-09-19  Pavel Tisnovsky  <ptisnovs@redhat.com>
+
+	* src/org/thermostat/qa/reporter/StringUtils.java:
+	JavaDoc improvements.
+
 2013-09-18  Jana Fabrikova  <jfabriko@redhat.com>
 
 	* scripts/stop_all_therm_agents.sh:

--- a/src/org/thermostat/qa/reporter/StringUtils.java	Wed Sep 18 16:09:51 2013 +0200
+++ b/src/org/thermostat/qa/reporter/StringUtils.java	Thu Sep 19 11:06:09 2013 +0200
@@ -47,20 +47,24 @@
 {
 
     /**
-     * Default locale used for character handling.
+     * Default locale used for character handling. This field is used for upper case
+     * to lower case and also for lower case to upper case conversions
      */
     private static final Locale DEFAULT_LOCALE = Locale.ENGLISH;
 
     /**
      * Get substring from given string in case that both delimiters are strings
-     * too.
+     * too (ie. not null). If the first or the second delimiter are set to null,
+     * 0 is used instead of the first delimiter and string.length() instead of
+     * the second delimiter. If delimiters can't be found in the given string,
+     * null is returned instead of substring.
      * 
      * @param string
      *            given input string
      * @param startDelimiter
-     *            first delimiter
+     *            first delimiter, might be null
      * @param stopDelimiter
-     *            second delimiter
+     *            second delimiter, might be null
      * @return substring a new string which is a substring of given input string
      */
     public static String getSubstring(String string, String startDelimiter, String stopDelimiter)
@@ -70,10 +74,12 @@
         {
             return null;
         }
+
         // compute start and stop delimiters
         int startDelimiterIndex = startDelimiter == null ? 0 : string.indexOf(startDelimiter);
         int stopDelimiterIndex = stopDelimiter == null ? string.length() : string.indexOf(stopDelimiter);
         int startDelimiterLength = startDelimiter == null ? 0 : startDelimiter.length();
+
         // when delimiters are not found, simply return null string
         if (startDelimiterIndex == -1)
         {
@@ -83,14 +89,17 @@
         {
             return null;
         }
+
         // get substring using computed delimiters
         String s = string.substring(startDelimiterIndex + startDelimiterLength, stopDelimiterIndex);
+
         // trim unnecessary leading and trailing whitespace characters
         return s.trim();
     }
 
     /**
-     * Convert UPPER_CASE_STYLE name into a CamelCase
+     * Convert UPPER_CASE_STYLE name into a CamelCase. Example:
+     * "VM_VERSION" is converted into "vmVersion"
      * 
      * @param string
      *            input string which could contains names divided by underscore
@@ -99,16 +108,30 @@
      */
     public static String toCamelCase(String string)
     {
-        // all underscores (+ one character after it) should be replaced by the
+        // all underscores should me removed from the string and one
+        // character following that underscore should be replaced by the
         // upper case variant of this character
         String[] parts = string.split("_");
+        StringBuffer camelCaseString = joinWordsUsingCamelcase(parts);
+        return camelCaseString.toString();
+    }
+
+    /**
+     * Join words using CamelCase style
+     * 
+     * @param parts
+     *            array of words
+     * @return camel case variant of all the words
+     */
+    private static StringBuffer joinWordsUsingCamelcase(String[] parts) {
         StringBuffer camelCaseString = new StringBuffer();
         // properly convert all words (which were separated by underscore)
+        // and create one string from them
         for (String part : parts)
         {
             camelCaseString.append(convertToProperCase(part));
         }
-        return camelCaseString.toString();
+        return camelCaseString;
     }
 
     /**
@@ -121,16 +144,19 @@
      */
     public static String convertToProperCase(String string)
     {
-        // only first letter should be in upper case
+        // only first letter should be in upper case,
+        // all other letters should be lower case
         return string.substring(0, 1).toUpperCase(DEFAULT_LOCALE) + string.substring(1).toLowerCase(DEFAULT_LOCALE);
     }
 
     /**
      * Convert "PLACEHOLDER_NAME" into the name of the getter:
-     * "getPlaceholderName"
+     * "getPlaceholderName".
      * 
      * @param placeholderName
-     * @return converted string
+     *            name of the placeholder in a form "PLACEHOLDER_NAME"
+     * @return converted string name of the corresponding getter in a form
+     *         "getPlaceholderName"
      */
     public static String getPlaceholderMethodName(String placeholderName)
     {
@@ -140,5 +166,5 @@
         temporaryName = "get" + StringUtils.toCamelCase(temporaryName.toLowerCase(DEFAULT_LOCALE));
         return temporaryName;
     }
-    
+
 }