Improve documentation

jtag/org.eclipse.cdt.debug.gdbjtag.core/src/org/eclipse/cdt/debug/gdbjtag/core/jtagdevice/IGDBJtagDevice.java

@@ -24,78 +24,133 @@ public interface IGDBJtagDevice {
 
 	/**
 	 * Device reset command
-	 * @param commands collection
+	 * 
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will reset the device, or leave the collection
+	 *            as-is if that operation is either unsupported or not
+	 *            applicable
 	 */
 	public void doReset(Collection<String> commands);
 
 	/**
 	 * Default device delay in millisecond
+	 * 
 	 * @return delay in second
 	 */
 	public int getDefaultDelay();
 
 	/**
 	 * Target needs some delay in order to initialize
-	 * @param delay delay in second
+	 * 
-	 * @param commands device specific delay commands
+	 * @param delay
+	 *            delay in second
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will carry out a delay, or leave the collection
+	 *            as-is if that operation is either unsupported or not
+	 *            applicable
 	 */
 	public void doDelay(int delay, Collection<String> commands);
 
 	/**
-	 * Target needs to be in pause mode in order to do
+	 * Target needs to be in pause mode in order to do JTAG debug. This should
-	 * JTAG debug. This should happen before the target
+	 * happen before the target MMU takes control
-	 * MMU takes control
+	 * 
-	 * @param commands device specific pause commands
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will halt the target, or leave the collection
+	 *            as-is if that operation is either unsupported or not
+	 *            applicable
 	 */
 	public void doHalt(Collection<String> commands);
 
 	/**
 	 * Commands to connect to remote JTAG device
-	 * @param ip host name of IP address of JTAG device
+	 * 
-	 * @param port TCP socket port number of JTAG device
+	 * @param ip
-	 * @param commands remote connection commands
+	 *            host name of IP address of JTAG device
+	 * @param port
+	 *            TCP socket port number of JTAG device
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will connect to the device, or leave the
+	 *            collection as-is if that operation is either unsupported or
+	 *            not applicable
 	 * @deprecated use @see IGDBJtagConnection#doRemote
 	 */
 	public void doRemote(String ip, int port, Collection<String> commands);
 
 	/**
 	 * Commands to download the executable binary to target
-	 * @param imageFileName executable binary file name
+	 * 
-	 * @param imageOffset executable binary memory offset
+	 * @param imageFileName
-	 * @param commands executable binary download commands
+	 *            executable binary file name
+	 * @param imageOffset
+	 *            executable binary memory offset
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will download the executable to the target, or
+	 *            leave the collection as-is if that operation is either
+	 *            unsupported or not applicable
 	 */
 	public void doLoadImage(String imageFileName, String imageOffset, Collection<String> commands);
 
 	/**
-	 * Commands to download the symbols file to target
+	 * Commands to get gdb to consume the symbolics information in the given
-	 * @param symbolFileName symbols file name
+	 * file
-	 * @param symbolOffset symbols file memory offset
+	 * 
-	 * @param commands symbols file download command
+	 * @param symbolFileName
+	 *            symbols file name
+	 * @param symbolOffset
+	 *            symbols file memory offset
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will process the symbolics file, or leave the
+	 *            collection as-is if that operation is either unsupported or
+	 *            not applicable
 	 */
 	public void doLoadSymbol(String symbolFileName, String symbolOffset, Collection<String> commands);
 
 	/**
 	 * Commands to set initial program counter
-	 * @param pc program counter
+	 * 
-	 * @param commands set program counter commands
+	 * @param pc
+	 *            program counter
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will set the PC, or leave the collection as-is
+	 *            if that operation is either unsupported or not applicable
 	 */
 	public void doSetPC(String pc, Collection<String> commands);
 
 	/**
 	 * Commands to set initial breakpoint
-	 * @param stopAt initial breakpoint location
+	 * 
-	 * @param commands set breakpoint commands
+	 * @param stopAt
+	 *            initial breakpoint location
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will set the initial breakpoint, or leave the
+	 *            collection as-is if that operation is either unsupported or
+	 *            not applicable
 	 */
 	public void doStopAt(String stopAt, Collection<String> commands);
 
 	/**
 	 * De-freeze the target in order to start debugging
-	 * @param commands commands to continue the target
+	 * 
+	 * @param commands
+	 *            implementation should populate the collection with the gdb
+	 *            commands that will resume the target, or leave the collection
+	 *            as-is if that operation is either unsupported or not
+	 *            applicable
 	 */
 	public void doContinue(Collection<String> commands);
 
 	/**
 	 * Device specific default hostname of IP address
+	 * 
 	 * @return default hostname of IP address
 	 * @deprecated use @see IGDBJtagConnection#getDetaultDeviceConnection
 	 */
@@ -103,9 +158,9 @@ public interface IGDBJtagDevice {
 
 	/**
 	 * Device specific default port number
+	 * 
 	 * @return default port number
 	 * @deprecated use @see IGDBJtagConnection#getDetaultDeviceConnection
 	 */
 	public String getDefaultPortNumber();
-
 }