Merge pull request #2888 from thc202/javadoc-tidy-up

Tidy up JavaDoc of some classes/methods

src/org/apache/commons/httpclient/HttpMethodBase.java

@@ -1848,7 +1848,6 @@ protected void processStatusLine(HttpState state, HttpConnection conn) {
      * Subclasses may want to override one or more of the above methods to to
      * customize the processing. (Or they may choose to override this method
      * if dramatically different processing is required.)
-     * </p>
      *
      * @param state the {@link HttpState state} information associated with this method
      * @param conn the {@link HttpConnection connection} used to execute

src/org/parosproxy/paros/CommandLine.java

@@ -32,6 +32,7 @@
 // ZAP: 2015/04/02 Issue 321: Support multiple databases and Issue 1582: Low memory option
 // ZAP: 2015/10/06 Issue 1962: Install and update add-ons from the command line
 // ZAP: 2016/08/19 Issue 2782: Support -configfile
+// ZAP: 2016/09/22 JavaDoc tweaks
 
 package org.parosproxy.paros;
 
@@ -361,14 +362,18 @@ private boolean parseKeywords(String[] args, int i) throws Exception {
     }
 
     /**
-     * @return Returns the noGUI.
+     * Tells whether or not ZAP was started with GUI.
+     * 
+     * @return {@code true} if ZAP was started with GUI, {@code false} otherwise
      */
     public boolean isGUI() {
         return GUI;
     }
 
     /**
-     * @param GUI The noGUI to set.
+     * Sets whether or not ZAP was started with GUI.
+     * 
+     * @param GUI {@code true} if ZAP was started with GUI, {@code false} otherwise
      */
     public void setGUI(boolean GUI) {
         this.GUI = GUI;
@@ -451,10 +456,9 @@ public boolean isEnabled(String keyword) {
     }
 
     /**
-     * A method for reporting informational messages in CommandLineListener.execute(..) implementations.
-     * It ensures that messages are written to the log file and/or written to stdout as appropriate.
-     * @param str
-     * @see org.parosproxy.paros.extension.CommandLineListener#execute()
+     * A method for reporting informational messages in {@link CommandLineListener#execute(CommandLineArgument[])}
+     * implementations. It ensures that messages are written to the log file and/or written to stdout as appropriate.
+     * @param str the informational message
      */
     public static void info(String str) {
     	switch (ZAP.getProcessType()) {
@@ -466,10 +470,9 @@ public static void info(String str) {
     }
 
     /**
-     * A method for reporting error messages in CommandLineListener.execute(..) implementations.
+     * A method for reporting error messages in {@link CommandLineListener#execute(CommandLineArgument[])} implementations.
      * It ensures that messages are written to the log file and/or written to stderr as appropriate.
-     * @param str
-     * @see org.parosproxy.paros.extension.CommandLineListener#execute()
+     * @param str the error message
      */
     public static void error(String str) {
     	switch (ZAP.getProcessType()) {
@@ -481,10 +484,10 @@ public static void error(String str) {
     }
 
     /**
-     * A method for reporting error messages in CommandLineListener.execute(..) implementations.
+     * A method for reporting error messages in {@link CommandLineListener#execute(CommandLineArgument[])} implementations.
      * It ensures that messages are written to the log file and/or written to stderr as appropriate.
-     * @param str
-     * @see org.parosproxy.paros.extension.CommandLineListener#execute()
+     * @param str the error message
+     * @param e the cause of the error
      */
     public static void error(String str, Throwable e) {
     	switch (ZAP.getProcessType()) {

src/org/parosproxy/paros/Constant.java

@@ -66,6 +66,7 @@
 // ZAP: 2016/06/07 Use filter directory in ZAP's home directory
 // ZAP: 2016/06/13 Migrate config option "proxy.modifyAcceptEncoding" 
 // ZAP: 2016/07/07 Convert passive scanners options to new structure
+// ZAP: 2016/09/22 JavaDoc tweaks
 
 package org.parosproxy.paros;
 
@@ -869,13 +870,12 @@ public static Locale getLocale () {
 	}
 
     /**
-     * Returns the system's {@code Locale} (as determined by the JVM at startup, {@code Locale#getDefault()}). Should be used to
+     * Returns the system's {@code Locale} (as determined by the JVM at startup, {@link Locale#getDefault()}). Should be used to
      * show locale dependent information in the system's locale.
      * <p>
      * <strong>Note:</strong> The default locale is overridden with the ZAP's user defined locale/language.
      *
      * @return the system's {@code Locale}
-     * @see Locale#getDefault()
      * @see Locale#setDefault(Locale)
      */
     public static Locale getSystemsLocale() {
@@ -1114,7 +1114,9 @@ public static boolean isLowMemoryOptionSet() {
     }
 
     /**
-     * Returns true if running on Kali and not a daily build 
+     * Tells whether or not ZAP is running in Kali (and it's not a daily build).
+     *
+     * @return {@code true} if running in Kali (and it's not daily build), {@code false} otherwise
      */
 	public static boolean isKali() {
 		if (onKali == null) {

src/org/parosproxy/paros/common/AbstractParam.java

@@ -26,6 +26,7 @@
 // ZAP: 2013/05/02 Re-arranged all modifiers into Java coding standard order
 // ZAP: 2014/01/17 Issue 987: Allow arbitrary config file values to be set via the command line
 // ZAP: 2014/02/21 Issue 1043: Custom active scan dialog
+// ZAP: 2016/09/22 JavaDoc tweaks
 
 package org.parosproxy.paros.common;
 
@@ -43,8 +44,9 @@ public abstract class AbstractParam implements Cloneable {
 
     private FileConfiguration config = null;
     /**
-     * Load this param from config
-     * @param config
+     * Loads the configurations from the given configuration file.
+     * 
+     * @param config the configuration file
      */
     public void load(FileConfiguration config) {
         this.config = config;
@@ -56,13 +58,24 @@ public void load(FileConfiguration config) {
         }
     }
 
-    public void load(String fileName) {
-    	this.load(fileName, null);
+    /**
+     * Loads the configurations from the file located at the given path.
+     * 
+     * @param filePath the path to the configuration file, might be relative.
+     */
+    public void load(String filePath) {
+    	this.load(filePath, null);
     }
 
-	public void load(String fileName, ControlOverrides overrides) {
+    /**
+     * Loads the configurations from the file located at the given path and using the given overrides
+     *
+     * @param filePath the path to the configuration file, might be relative.
+     * @param overrides the configuration overrides, might be {@code null}.
+     */
+	public void load(String filePath, ControlOverrides overrides) {
         try {
-            config = new ZapXmlConfiguration(fileName);
+            config = new ZapXmlConfiguration(filePath);
             if (overrides != null) {
                 for (Entry<String,String> entry : overrides.getConfigs().entrySet()) {
                 	logger.info("Setting config " + entry.getKey() + " = " + entry.getValue() + 
@@ -76,6 +89,11 @@ public void load(String fileName, ControlOverrides overrides) {
         }
 	}
 
+    /**
+     * Gets the configuration file, previously loaded.
+     *
+     * @return the configurations file
+     */
     public FileConfiguration getConfig() {
         return config;
     } 
@@ -93,8 +111,11 @@ public AbstractParam clone()  {
     }
 
     /**
-     * Implement by subclass to parse the config file.
-     *
+     * Parses the configurations.
+     * <p>
+     * Called each time the configurations are loaded.
+     * 
+     * @see #getConfig()
      */
     protected abstract void parse();
 }

src/org/parosproxy/paros/common/ThreadPool.java

@@ -19,6 +19,7 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  */
 // ZAP: 2014/04/01 Changed to allow to set a name to created threads.
+// ZAP: 2016/09/22 JavaDoc tweaks
 package org.parosproxy.paros.common;
 
 
@@ -37,8 +38,11 @@ public ThreadPool(int maxThreadCount, String threadsBaseName) {
 	}
 
 	/**
-	Get a free thread from thread pool.  If there is no free thread, return null
-	*/
+	 * Gets a free thread from the thread pool. If there is no free thread, returns {@code null}.
+	 * 
+	 * @param runnable the {@code Runnable} to be run in the thread
+	 * @return the {@code Thread}, already started, with the given {@code Runnable}, or {@code null} if none available.
+	 */
 	public synchronized Thread getFreeThreadAndRun(Runnable runnable) {
 
 		for (int i=0; i<pool.length; i++) {
@@ -56,9 +60,11 @@ public synchronized Thread getFreeThreadAndRun(Runnable runnable) {
 	}
 
 	/**
-	Wait until all thread completed tasks (at most some time for each).
-	If not completed yet, do not wait.  Each thread should kill itself.
-	*/
+	 * Waits until all threads finish its tasks (at most some time for each).
+	 * <p>
+	 * If not completed yet, do not wait. Each thread should kill itself.
+	 * @param waitInMillis the number of milliseconds to wait for the threads
+	 */
 	public void waitAllThreadComplete(int waitInMillis) {
 		for (int i=0; i<pool.length; i++) {
 			if (pool[i] != null && pool[i].isAlive()) {

src/org/parosproxy/paros/core/proxy/OverrideMessageProxyListener.java

@@ -49,7 +49,6 @@ public interface OverrideMessageProxyListener extends ArrangeableProxyListener {
      * <li>the message will really be forwarded to the server, even if the return value is {@code false}, as the following
      * {@code ProxyListener}s may drop it.</li>
      * </ul>
-     * </p>
      * 
      * @param msg the {@code HttpMessage} that may be overridden and not forwarded to the server
      * @return {@code true} if the message should be overridden and not forward to the server, {@code false} otherwise
@@ -70,7 +69,6 @@ public interface OverrideMessageProxyListener extends ArrangeableProxyListener {
      * <li>the message will really be forwarded to the client, even if the return value is {@code false}, as the following
      * {@code ProxyListener}s may drop it.</li>
      * </ul>
-     * </p>
      * 
      * @param msg the {@code HttpMessage} that may be forwarded to the client
      * @return {@code true} if the message should be forwarded to the client, {@code false} otherwise

src/org/parosproxy/paros/core/proxy/ProxyListener.java

@@ -22,6 +22,7 @@
 // ZAP: 2012/03/15 Added the method getProxyListenerOrder.
 // ZAP: 2012/06/17 Documented the interface.
 // ZAP: 2012/12/27 Extend from ArrangeableListener.
+// ZAP: 2016/09/22 JavaDoc tweaks
 package org.parosproxy.paros.core.proxy;
 
 import org.parosproxy.paros.network.HttpMessage;
@@ -46,8 +47,6 @@ public interface ProxyListener extends ArrangeableProxyListener {
      * the value is {@code false} the message <i>will not</i> be forwarded and
      * no more listeners will be notified.
      * <p>
-     * 
-     * <p>
      * <strong>Note:</strong> In the presence of more than one listener there
      * are <i>no</i> guarantees that:
      * <ul>
@@ -57,7 +56,6 @@ public interface ProxyListener extends ArrangeableProxyListener {
      * return value is {@code true}, as the following listeners may return
      * {@code false}.</li>
      * </ul>
-     * </p>
      * 
      * @param msg
      *            the {@code HttpMessage} that may be forwarded to the server
@@ -77,8 +75,6 @@ public interface ProxyListener extends ArrangeableProxyListener {
      * the value is {@code false} the message <i>will not</i> be forwarded and
      * no more listeners will be notified.
      * <p>
-     * 
-     * <p>
      * <strong>Note:</strong> In the presence of more than one listener there
      * are <i>no</i> guarantees that:
      * <ul>
@@ -88,7 +84,6 @@ public interface ProxyListener extends ArrangeableProxyListener {
      * return value is {@code true}, as the following listeners may return
      * {@code false}.</li>
      * </ul>
-     * </p>
      * 
      * @param msg
      *            the {@code HttpMessage} that may be forwarded to the client

src/org/parosproxy/paros/core/proxy/ProxyServer.java

@@ -31,6 +31,7 @@
 // ZAP: 2014/08/14 Issue 1312: Misleading error message when unable to bind the local proxy to specified address
 // ZAP: 2015/11/04 Issue 1920: Report the host:port ZAP is listening on in daemon mode, or exit if it cant
 // ZAP: 2016/05/30 Issue 2494: ZAP Proxy is not showing the HTTP CONNECT Request in history tab
+// ZAP: 2016/09/22 JavaDoc tweaks
 
 package org.parosproxy.paros.core.proxy;
 
@@ -122,8 +123,15 @@ public ConnectionParam getConnectionParam() {
     }
 
     /**
-     *
-     * @return	true = the server is started successfully.
+     * Starts the proxy server.
+     * <p>
+     * If the proxy server was already running it's stopped first.
+     * 
+     * @param ip the IP/address the server should bind to
+     * @param port the port
+     * @param isDynamicPort {@code true} if it should use another port if the given one is already in use, {@code false}
+     *            otherwise.
+     * @return the port the server is listening to, or {@code -1} if not able to start
      */
     public synchronized int startServer(String ip, int port, boolean isDynamicPort) {
 
@@ -203,9 +211,9 @@ private static void handleUnknownException(Exception e) {
     }
 
     /**
-     * Stop this server
+     * Stops the proxy server.
      *
-     * @return true if server can be stopped.
+     * @return {@code true} if the proxy server was stopped, {@code false} if it was not running.
      */
     public synchronized boolean stopServer() {
 

src/org/parosproxy/paros/core/proxy/ProxyThread.java

@@ -61,6 +61,7 @@
 // ZAP: 2016/04/29 Adjust exception logging levels and log when timeouts happen
 // ZAP: 2016/05/30 Issue 2494: ZAP Proxy is not showing the HTTP CONNECT Request in history tab
 // ZAP: 2016/06/13 Remove all unsupported encodings (instead of just some)
+// ZAP: 2016/09/22 JavaDoc tweaks
 
 package org.parosproxy.paros.core.proxy;
 
@@ -164,7 +165,7 @@ public void start() {
 
 	/**
 	 * @param targethost the host where you want to connect to
-	 * @throws IOException
+	 * @throws IOException if an error occurred while establishing the SSL/TLS connection
 	 */
 	private void beginSSL(String targethost) throws IOException {
 		// ZAP: added parameter 'targethost'
@@ -553,7 +554,8 @@ protected void disconnect() {
 	/**
 	 * Go through each observers to process a request in each observers.
 	 * The method can be modified in each observers.
-	 * @param httpMessage
+	 * @param httpMessage the request that was received from the client and may be forwarded to the server
+	 * @return {@code true} if the message should be forwarded to the server, {@code false} otherwise
 	 */
 	private boolean notifyListenerRequestSend(HttpMessage httpMessage) {
 		if (parentServer.excludeUrl(httpMessage.getRequestHeader().getURI())) {
@@ -577,7 +579,8 @@ private boolean notifyListenerRequestSend(HttpMessage httpMessage) {
 	/**
 	 * Go thru each observers and process the http message in each observers.
 	 * The msg can be changed by each observers.
-	 * @param msg
+	 * @param httpMessage the response that was received from the server and may be forwarded to the client
+	 * @return {@code true} if the message should be forwarded to the client, {@code false} otherwise
 	 */
 	private boolean notifyListenerResponseReceive(HttpMessage httpMessage) {
 		if (parentServer.excludeUrl(httpMessage.getRequestHeader().getURI())) {
@@ -628,7 +631,7 @@ private boolean notifyOverrideListenersResponseReceived(HttpMessage httpMessage)
 	 * Go thru each listener and offer him to take over the connection. The
 	 * first observer that returns true gets exclusive rights.
 	 * 
-	 * @param httpMessage Contains HTTP request & response.
+	 * @param httpMessage Contains HTTP request & response.
 	 * @param inSocket Encapsulates the TCP connection to the browser.
 	 * @param method Provides more power to process response.
 	 * 

src/org/parosproxy/paros/db/TableHistory.java

@@ -119,16 +119,10 @@ void delete(List<Integer> ids, int batchSize)
 			throws DatabaseException;
 
 	/**
-	 * Deletes all records whose history type was marked as temporary (by calling {@code setHistoryTypeTemporary(int)}).
-	 * <p>
-	 * By default the only temporary history types are {@code HistoryReference#TYPE_TEMPORARY} and
-	 * {@code HistoryReference#TYPE_SCANNER_TEMPORARY}.
+	 * Deletes all records whose history type was marked as temporary.
 	 *
 	 * @throws DatabaseException if an error occurred while deleting the temporary history records
-	 * @see #setHistoryTypeAsTemporary(int)
-	 * @see #unsetHistoryTypeAsTemporary(int)
-	 * @see HistoryReference#TYPE_TEMPORARY
-	 * @see HistoryReference#TYPE_SCANNER_TEMPORARY
+	 * @see HistoryReference#getTemporaryTypes()
 	 */
 	void deleteTemporary() throws DatabaseException;