From 3d3457f45821ee5e8b87b4e5e91ce7b9ae505721 Mon Sep 17 00:00:00 2001
From: Sebastian Bazley <sebb@apache.org>
Date: Mon, 25 Jun 2012 16:31:24 +0000
Subject: [PATCH] Javadoc

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1353642 13f79535-47bb-0310-9956-ffa450edef68
---
 .../http/client/utils/URLEncodedUtils.java    | 48 ++++++++++++++++++-
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/httpclient/src/main/java/org/apache/http/client/utils/URLEncodedUtils.java b/httpclient/src/main/java/org/apache/http/client/utils/URLEncodedUtils.java
index 51be6d706..e2b6c3d2a 100644
--- a/httpclient/src/main/java/org/apache/http/client/utils/URLEncodedUtils.java
+++ b/httpclient/src/main/java/org/apache/http/client/utils/URLEncodedUtils.java
@@ -309,6 +309,14 @@ public static String format (
 
     private static final int RADIX = 16;
 
+    /**
+     * Emcode/escape a portion of a URL, to use with the query part ensure {@code plusAsBlank} is true.
+     * 
+     * @param content the portion to decode
+     * @param charset the charset to use
+     * @param blankAsPlus if {@code true}, then convert space to '+' (e.g. for www-url-form-encoded content), otherwise leave as is.
+     * @return
+     */
     private static String urlencode(
             final String content,
             final Charset charset,
@@ -338,6 +346,14 @@ private static String urlencode(
         return buf.toString();
     }
 
+    /**
+     * Decode/unescape a portion of a URL, to use with the query part ensure {@code plusAsBlank} is true.
+     * 
+     * @param content the portion to decode
+     * @param charset the charset to use
+     * @param plusAsBlank if {@code true}, then convert '+' to space (e.g. for www-url-form-encoded content), otherwise leave as is.
+     * @return
+     */
     private static String urldecode(
             final String content,
             final Charset charset,
@@ -371,6 +387,13 @@ private static String urldecode(
         return charset.decode(bb).toString();
     }
 
+    /**
+     * Decode/unescape www-url-form-encoded content.
+     * 
+     * @param content the content to decode, will decode '+' as space
+     * @param charset the charset to use
+     * @return
+     */
     private static String decode (final String content, final String charset) {
         if (content == null) {
             return null;
@@ -378,6 +401,13 @@ private static String decode (final String content, final String charset) {
         return urldecode(content, charset != null ? Charset.forName(charset) : Consts.UTF_8, true);
     }
 
+    /**
+     * Decode/unescape www-url-form-encoded content.
+     * 
+     * @param content the content to decode, will decode '+' as space
+     * @param charset the charset to use
+     * @return
+     */
     private static String decode (final String content, final Charset charset) {
         if (content == null) {
             return null;
@@ -385,6 +415,13 @@ private static String decode (final String content, final Charset charset) {
         return urldecode(content, charset != null ? charset : Consts.UTF_8, true);
     }
 
+    /**
+     * Encode/escape www-url-form-encoded content.
+     * 
+     * @param content the content to encode, will convert space to '+'
+     * @param charset the charset to use
+     * @return
+     */
     private static String encode(final String content, final String charset) {
         if (content == null) {
             return null;
@@ -393,6 +430,13 @@ private static String encode(final String content, final String charset) {
             Consts.UTF_8, UNRESERVED, true);
     }
 
+    /**
+     * Encode/escape www-url-form-encoded content.
+     * 
+     * @param content the content to encode, will convert space to '+'
+     * @param charset the charset to use
+     * @return
+     */
     private static String encode(final String content, final Charset charset) {
         if (content == null) {
             return null;
@@ -403,7 +447,7 @@ private static String encode(final String content, final Charset charset) {
     /**
      * Encode a String using the {@link #SAFE} set of characters.
      *
-     * @param content the string to encode
+     * @param content the string to encode, does not convert space to '+'
      * @param charset the charset to use
      * @return the encoded string
      */
@@ -414,7 +458,7 @@ static String enc(final String content, final Charset charset) {
     /**
      * Encode a String using the {@link #PATHSAFE} set of characters.
      *
-     * @param content the string to encode
+     * @param content the string to encode, does not convert space to '+'
      * @param charset the charset to use
      * @return the encoded string
      */