HTTPCLIENT-933: javadoc improvements

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@940214 13f79535-47bb-0310-9956-ffa450edef68

httpclient/src/main/java/org/apache/http/conn/scheme/PlainSocketFactory.java

@@ -85,6 +85,10 @@ public final class PlainSocketFactory implements SocketFactory, SchemeSocketFact
     }
 
     /**
+     * @param params Optional parameters. Parameters passed to this method will have no effect.
+     *               This method will create a unconnected instance of {@link Socket} class
+     *               using default constructor.
+     * 
      * @since 4.1
      */
     public Socket createSocket(final HttpParams params) {

httpclient/src/main/java/org/apache/http/conn/scheme/SchemeSocketFactory.java

@@ -47,7 +47,14 @@ public interface SchemeSocketFactory {
      * Creates a new, unconnected socket. The socket should subsequently be passed to
      * {@link #connectSocket(Socket, InetSocketAddress, InetSocketAddress, HttpParams)}.
      *
-     * @param params    additional {@link HttpParams parameters}
+     * @param params    Optional {@link HttpParams parameters}. In most cases these parameters
+     *                  will not be required and will have no effect, as usually socket 
+     *                  initialization should take place in the 
+     *                  {@link #connectSocket(Socket, InetSocketAddress, InetSocketAddress, HttpParams)}
+     *                  method. However, in rare cases one may want to pass additional parameters
+     *                  to this method in order to create a customized {@link Socket} instance,
+     *                  for instance bound to a SOCKS proxy server.
+     *                  
      * @return  a new socket
      *
      * @throws IOException if an I/O error occurs while creating the socket

httpclient/src/main/java/org/apache/http/conn/ssl/SSLSocketFactory.java

@@ -335,6 +335,9 @@ public class SSLSocketFactory implements LayeredSchemeSocketFactory, LayeredSock
     }
 
     /**
+     * @param params Optional parameters. Parameters passed to this method will have no effect.
+     *               This method will create a unconnected instance of {@link Socket} class
+     *               using {@link javax.net.ssl.SSLSocketFactory#createSocket()} method.
      * @since 4.1
      */
     @SuppressWarnings("cast")