Updated comments.

5 files changed, 55 insertions, 15 deletions

diff --git a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPJob.java b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPJob.java
index 6355eece6..5f385fff6 100644
--- a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPJob.java
+++ b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPJob.java
@@ -37,14 +37,14 @@ import org.eclipse.ptp.core.elements.listeners.IJobListener;
 public interface IPJob extends IPElement {
 	
 	/**
-	 * Add a listener for child events.
+	 * Add a listener for child events relating to this job.
 	 * 
 	 * @param listener
 	 */
 	public void addChildListener(IJobChildListener listener);
 
 	/**
-	 * Add a listner for element events.
+	 * Add a listener for events related to this job.
 	 * 
 	 * @param listener
 	 */
@@ -91,8 +91,8 @@ public interface IPJob extends IPElement {
 	public IPProcess getProcessByIndex(String number);
 	
 	/**
-	 * Returns an array of the Processes comprised by this Job. Might return
-	 * <code>null</code> if no Processes have yet been assigned.
+	 * Returns an array of the Processes comprised by this Job. 
+	 * Returns an empty array if there are no processes.
 	 * 
 	 * @return The Processes in this Job.
 	 */
@@ -120,14 +120,14 @@ public interface IPJob extends IPElement {
 	public boolean isDebug();
 
 	/**
-	 * Remove a listener for child events.
+	 * Remove a listener for events relating to children of this job.
 	 * 
 	 * @param listener
 	 */
 	public void removeChildListener(IJobChildListener listener);
 	
 	/**
-	 * Remove a listener for element events.
+	 * Remove a listener for events relating to this job.
 	 * 
 	 * @param listener
 	 */
diff --git a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPMachine.java b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPMachine.java
index b5faf1317..9d3b234c4 100644
--- a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPMachine.java
+++ b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPMachine.java
@@ -19,8 +19,8 @@
 package org.eclipse.ptp.core.elements;
 
 import org.eclipse.ptp.core.elements.attributes.MachineAttributes;
-import org.eclipse.ptp.core.elements.listeners.IMachineListener;
 import org.eclipse.ptp.core.elements.listeners.IMachineChildListener;
+import org.eclipse.ptp.core.elements.listeners.IMachineListener;
 
 
 /**
@@ -36,11 +36,15 @@ import org.eclipse.ptp.core.elements.listeners.IMachineChildListener;
 public interface IPMachine extends IPElement {
 	
 	/**
+	 * Add a listener for events related to children of this machine.
+	 * 
 	 * @param listener
 	 */
 	public void addChildListener(IMachineChildListener listener);
 
 	/**
+	 * Add a listener for events related to this machine.
+	 * 
 	 * @param listener
 	 */
 	public void addElementListener(IMachineListener listener);
@@ -64,8 +68,8 @@ public interface IPMachine extends IPElement {
 	public IPNode getNodeById(String id);
 
 	/**
-	 * Returns an array of all the Nodes that this Machine is comprised of. May
-	 * return null if there are none.
+	 * Returns an array of all the Nodes that this Machine is comprised of. 
+	 * Returns an empty array if there are no nodes.
 	 * 
 	 * @return The Nodes in this Machine - <code>null</code> if there are
 	 *         none.
@@ -73,6 +77,8 @@ public interface IPMachine extends IPElement {
 	public IPNode[] getNodes();
 	
 	/**
+	 * Get the resource manager that controls this machine.
+	 * 
 	 * @return the machine's parent resource manager
 	 */
 	public IResourceManager getResourceManager();
@@ -85,11 +91,15 @@ public interface IPMachine extends IPElement {
 	public MachineAttributes.State getState();
 
 	/**
+	 * Add a listener for events related to children of this machine.
+	 * 
 	 * @param listener
 	 */
 	public void removeChildListener(IMachineChildListener listener);
 
 	/**
+	 * Add a listener for events related to this machine.
+	 * 
 	 * @param listener
 	 */
 	public void removeElementListener(IMachineListener listener);
diff --git a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPNode.java b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPNode.java
index 05b6be154..a37c5e2a8 100644
--- a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPNode.java
+++ b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPNode.java
@@ -19,18 +19,22 @@
 package org.eclipse.ptp.core.elements;
 
 import org.eclipse.ptp.core.elements.attributes.NodeAttributes;
-import org.eclipse.ptp.core.elements.listeners.INodeListener;
 import org.eclipse.ptp.core.elements.listeners.INodeChildListener;
+import org.eclipse.ptp.core.elements.listeners.INodeListener;
 
 
 public interface IPNode extends IPElement {
 
 	/**
+	 * Add a listener for events related to children of this node.
+	 * 
 	 * @param listener
 	 */
 	public void addChildListener(INodeChildListener listener);
 
 	/**
+	 * Add a listener for events related to this node.
+	 * 
 	 * @param listener
 	 */
 	public void addElementListener(INodeListener listener);
@@ -53,6 +57,7 @@ public interface IPNode extends IPElement {
 
 	/**
 	 * Return any processes that are linked to this node
+	 * Returns an empty array if there are no processes.
 	 * 
 	 * @return array of processes
 	 */
@@ -66,11 +71,15 @@ public interface IPNode extends IPElement {
 	public NodeAttributes.State getState();
 
 	/**
+	 * Remove a listener for events related to children of this node.
+	 * 
 	 * @param listener
 	 */
 	public void removeChildListener(INodeChildListener listener);
 	
 	/**
+	 * Remove a listener for events related to this node.
+	 * 
 	 * @param listener
 	 */
 	public void removeElementListener(INodeListener listener);
diff --git a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPQueue.java b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPQueue.java
index edb725488..0af6f7452 100644
--- a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPQueue.java
+++ b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IPQueue.java
@@ -25,27 +25,39 @@ import org.eclipse.ptp.core.elements.listeners.IQueueListener;
 public interface IPQueue extends IPElement {
 
 	/**
+	 * Add a listener for events related to children of this queue.
+	 * 
 	 * @param listener
 	 */
 	public void addChildListener(IQueueChildListener listener);
 
 	/**
+	 * Add a listener for events related to this queue.
+	 * 
 	 * @param listener
 	 */
 	public void addElementListener(IQueueListener listener);
 
 	/**
+	 * Find a job object using its ID.
+	 * Returns null if no job is found.
+	 * 
 	 * @param job_id
 	 * @return IPJob
 	 */
 	public IPJob getJobById(String job_id);
 
 	/**
-	 * @return IPJob[]
+	 * Get the jobs in this queue. 
+	 * Returns an empty array if there are no jobs
+	 * 
+	 * @return array of jobs in this queue
 	 */
 	public IPJob[] getJobs();
 
 	/**
+	 * Get the resource manager that controls this queue.
+	 * 
 	 * @return IResourceManager
 	 */
 	public IResourceManager getResourceManager();
@@ -58,11 +70,15 @@ public interface IPQueue extends IPElement {
 	public QueueAttributes.State getState();
 	
 	/**
+	 * Remove a listener for events related to children of this queue.
+	 * 
 	 * @param listener
 	 */
 	public void removeChildListener(IQueueChildListener listener);
 	
 	/**
+	 * Remove a listener for events related to this queue.
+	 * 
 	 * @param listener
 	 */
 	public void removeElementListener(IQueueListener listener);
diff --git a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IResourceManager.java b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IResourceManager.java
index 8829b8fd4..a4a5a1e77 100644
--- a/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IResourceManager.java
+++ b/core/org.eclipse.ptp.core/src/org/eclipse/ptp/core/elements/IResourceManager.java
@@ -64,6 +64,7 @@ public interface IResourceManager extends IPElement,
 	
 	/**
 	 * Find a machine object using its ID
+	 * Returns null if no machine is found.
 	 * 
 	 * @param id ID of the machine object
 	 * @return machine object corresponding to the ID
@@ -71,7 +72,8 @@ public interface IResourceManager extends IPElement,
 	public IPMachine getMachineById(String id);
 	
 	/**
-	 * Get an array containing all the machines known by this RM
+	 * Get an array containing all the machines known by this RM.
+	 * If there are no machines, an empty array is returned.
 	 * 
 	 * @return array of machines known by this RM
 	 */
@@ -85,7 +87,8 @@ public interface IResourceManager extends IPElement,
 	public String getName();
 
 	/**
-	 * Find a queue object using its ID
+	 * Find a queue object using its ID.
+	 * Returns null if no queue is found.
 	 * 
 	 * @param id ID of the queue object
 	 * @return queue object corresponding to the ID
@@ -93,7 +96,8 @@ public interface IResourceManager extends IPElement,
 	public IPQueue getQueueById(String id);
 
 	/**
-	 * Fina a queue object using its name attribute
+	 * Find a queue object using its name attribute.
+	 * Returns null if no queue is found.
 	 * 
 	 * @param name name attribute of the queue object
 	 * @return queue object corresponding to the name
@@ -101,7 +105,8 @@ public interface IResourceManager extends IPElement,
 	public IPQueue getQueueByName(String name);
 
 	/**
-	 * Get an array containing all the queues known by this RM
+	 * Get an array containing all the queues known by this RM.
+	 * If there are no queues, an empty array is returned.
 	 * 
 	 * @return array of queues known by this RM
 	 */