Improve Javadoc of IHostFile#getFile()

rse/plugins/org.eclipse.rse.services.ssh/src/org/eclipse/rse/internal/services/ssh/files/SftpFileService.java

@@ -245,9 +245,10 @@ public class SftpFileService extends AbstractFileService implements IFileService
 	
 	public IHostFile getFile(String remoteParent, String fileName, IProgressMonitor monitor) throws SystemMessageException
 	{
-		//TODO getFile() must return a dummy even for non-existent files,
-		//or the move() operation will fail. This needs to be described in 
+		//getFile() must return a dummy even for non-existent files,
+		//or the move() operation will fail. This is described in 
 		//the API docs.
+		//TODO when monitor is canceled, it is unclear whether we should return an empty file node or throw a canceled exception.
 		SftpHostFile node = null;
 		SftpATTRS attrs = null;
 		if (fDirChannelMutex.waitForLock(monitor, fDirChannelTimeout)) {

rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java

@@ -94,7 +94,10 @@ public interface IFileService extends IService
 	 * @param remoteParent
 	 * @param name
 	 * @param monitor the monitor for this potentially long running operation
-	 * @return the host file given the parent path and file name
+	 * @return the host file given the parent path and file name.
+	 *     Must not return <code>null</code>, non-existing files should be
+	 *     reported with an IHostFile object where {@link IHostFile#exists()}
+	 *     returns <code>false</code>.
 	 * @throws SystemMessageException if an error occurs. 
 	 * Typically this would be one of those in the RemoteFileException family.
 	 */