[cleanup] update javadoc

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

@@ -30,6 +30,7 @@ package org.eclipse.rse.services.files;
 public interface IHostFile {
 	/**
 	 * Gets the simple name of the file object on the remote system.
+	 * 
 	 * @return The name of the file object on the remote system devoid of any qualifying path
 	 * information.
 	 */
@@ -37,6 +38,7 @@ public interface IHostFile {
 
 	/**
 	 * Gets the absolute path name of the parent object of this object on the remote file system.
+	 * 
 	 * @return The fully qualified path of any parent object for this file. This would typically be the
 	 * string representation of the absolute path as interpreted by the remote file system. Returns 
 	 * <code>null</code> if {@link #isRoot()} is true.
@@ -44,16 +46,19 @@ public interface IHostFile {
 	public String getParentPath();
 
 	/**
-	 * Gets the fully qualified path to this object in the remote file system. The name is constructed
+	 * Gets the fully qualified path to this object in the remote file system.
-	 * as it would be used on the remote file system.  
+	 * 
-	 * @return a string representing the path name. This string can be interpreted and used by its file service 
+	 * The name is constructed as it would be used on the remote file system. 
-	 * to locate this object on the remote file system beginning 
+	 * This string can be interpreted and used by its file service to locate 
-	 * at the file system root.
+	 * this object on the remote file system beginning at the file system root.
+	 *    
+	 * @return a String representing the path name. Never returns <code>null</code>. 
 	 */
 	public String getAbsolutePath();
 
 	/**
 	 * Determines if the file system object is hidden on the remote file system.
+	 * 
 	 * @return true if and only if the file on the remote system has a "hidden" attribute or a naming
 	 * convention that would normal indicate that it was hidden when listing the contents of its parent
 	 * on that file system. It is up to the file services to conform to the correct notion of "hidden" for
@@ -63,6 +68,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object is a directory on the remote file system.
+	 * 
 	 * @return true if and only if the object on the remote system is a directory. That is, it contains 
 	 * entries that can be interpreted as other IHostFile objects. A return value of true does not
 	 * necessarily imply that isFile() returns false.
@@ -71,6 +77,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object is a "root" directory on the remote file system.
+	 * 
 	 * @return true if and only if the object on the remote system is a directory whose simple name and
 	 * absolute path name are the same.
 	 */
@@ -78,6 +85,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object is a file on the remote file system.
+	 * 
 	 * @return true if and only if the object on the remote system can be considered to have "contents" that
 	 * have the potential to be read and written as a byte or character stream. A return value of true 
 	 * does not necessarily imply that {@link #isDirectory()} returns false.
@@ -86,6 +94,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object is "writeable" on the remote file system.
+	 * 
 	 * @return true if and only if the object on the remote system is a file that can be written. This could
 	 * mean that there is write permission granted to this user or perhaps a "writable" attribute is set for the 
 	 * file. It is up to the file services to conform to the correct notion of "writable" for the remote
@@ -96,6 +105,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object is "readable" on the remote file system.
+	 * 
 	 * @return true if and only if the object on the remote system is a file that can be read. This could
 	 * mean that there is read permission granted to this user or perhaps a "readable" attribute is set for the 
 	 * file. It is up to the file services to conform to the correct notion of "readable" for the remote
@@ -106,6 +116,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object exists on the remote file system.
+	 * 
 	 * @return true if and only if the remote object represented by this object exists
 	 * in the remote file system. Symbolic links on a UNIX file system exist even if
 	 * the target they point to does not exist.
@@ -114,6 +125,7 @@ public interface IHostFile {
 
 	/**
 	 * Determines if the file system object represents an archive on the remote file system.
+	 * 
 	 * @return true if and only if the remote object is a file that can be "extracted" to contain other files.
 	 * Examples would be tar and zip files. It is up to the file services to conform to the correct notion of 
 	 * "archive" for the remote systems they support. If a file service creates an object with
@@ -124,13 +136,15 @@ public interface IHostFile {
 	/**
 	 * Gets the size of the file system object on the remote file system in bytes if isFile() is true.
 	 * If the storage unit on the remote system is not bytes then the file service creating this must
-	 * convert the remote value to bytes. 
+	 * convert the remote value to bytes.
+	 *  
 	 * @return the size in bytes of the file if {@link #isFile()} is true, 0L otherwise.
 	 */
 	public long getSize();
 
 	/**
 	 * Gets a timestamp representing the date and time of last modification to the file.
+	 * 
 	 * @return the timestamp as obtained from the remote file system.
 	 * The timestamp represents the time the file was modified in milliseconds from January 1, 1970, 00:00:00 UTC.
 	 * Note that even so, comparison of timestamps between systems should be avoided since clock resolution and 

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.java

@@ -64,37 +64,55 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
 	 * is returned from this query, in which only a couple properties are shown.
 	 */
 	public boolean showBriefPropertySet();
+	
 	/**
-	 * Get parent subsystem
+	 * Get parent subsystem.
+	 * 
+	 * @return the Subsystem holding this file.
 	 */
 	public IRemoteFileSubSystem getParentRemoteFileSubSystem();
+	
     /**
      * Return the separator character for this file system: \ or /.
      * Queries it from the subsystem factory.
+     * 
+     * @return the separator character for this file system.
      */
     public char getSeparatorChar();
+    
     /**
      * Return the separator character for this file system, as a string: "\" or "/".
      * Queries it from the subsystem factory.
+     * 
+     * @return the separator character for this file system as a String.
      */
+    
     public String getSeparator();
+    
 	/**
 	 * Return as a string the line separator for this file system
 	 * Queries it from the subsystem factory.
 	 */
 	public String getLineSeparator();
+	
     /**
      * Return the connection this remote file is from.
      */
     public IHost getSystemConnection();
+    
     /**
-     * Return the parent remote file object expanded to get this object, or null if no such parent
+     * Return the parent remote file object expanded to get this object,
+     * or <code>null</nul> if no such parent exists.
+     * 
+     * @return the parent remote file object or <code>null</code>.
      */
     public IRemoteFile getParentRemoteFile();
+    
     /**
      * Return the filter string resolved to get this object
      */
     public RemoteFileFilterString getFilterString();
+    
     /**
      * If this is a folder, it is possible that it is listed as part of a multiple filter string
      *  filter. In this case, when the folder is expanded, we want to filter the file names to 
@@ -104,10 +122,15 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      *  same parent path as was used to produce this file. 
      */
     public RemoteFileFilterString[] getAllFilterStrings();
+    
     /**
      * Get fully qualified name: root plus path plus name. No connection name.
+     * 
+     * @return the fully qualified path for uniquely addressing this file 
+     *     on the remote host. Never returns <code>null</code>. 
      */
     public String getAbsolutePath();
+    
     /**
      * Get fully qualified connection and file name: profile.connection\path\file.
      * Note the separator character between the profile name and the connection name is always '.'
@@ -126,6 +149,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * If this object represents only a root drive, this is the same as getRoot().
      */
     public String getName();
+    
     /**
      * Get fully qualified path and name of folder containing this file or folder.
      * Returns the root and path. No file name, and no ending separator.
@@ -135,6 +159,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * Example: <code>c:\folder1\folder2\file1.ext</code> results in <code>c:\folder1\folder2</code>
      */
     public String getParentPath();
+    
     /**
      * Get fully qualified path and name of folder containing this file or folder, minus the root.
      * Returns the path. No root prefix. No file name, and no ending separator. 
@@ -143,7 +168,8 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * <p>
      * Example: <code>c:\folder1\folder2\file1.ext</code> results in <code>folder1\folder2</code>
      */
-    public String getParentNoRoot();    
+    public String getParentNoRoot();
+    
     /**
      * Get the root part of the name.
      * <p>
@@ -153,6 +179,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * </ul>
      */
     public String getRoot();
+    
     /**
      * Get the unqualified name of the parent directory containing this file or folder.
      * Compare this to getParent() that returns the fully qualified parent directory.
@@ -161,45 +188,53 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * Example: <code>c:\folder1\folder2\file1.ext</code> results in <code>folder2</code>
      */
     public String getParentName();
+    
 	/**
 	 * Return the extension part of a file name.
 	 * Eg, for abc.java, return "java"
 	 */
 	public String getExtension();
+	
     /**
      * Returns true if this represents a root folder (eg: c:\\ or /).
      */
     public boolean isRoot();
+    
     /**
      * Returns true if this represents a folder (eg: c:\\folder)
      */
     public boolean isDirectory();
+    
     /**
      * Returns true if this represents a file, versus a root or folder
      */
-    public boolean isFile();    
+    public boolean isFile();
+    
     /**
      * Returns true if this represents an archive file, versues a non-archive file
      */    
     public boolean isArchive();
     
-
     /**
      * Returns true if this is a binary file
      */
     public boolean isBinary();
+    
     /**
      * Returns true if this is a text file
      */
-    public boolean isText();    
+    public boolean isText();
+    
     /**
      * Returns true if this is a hidden file.
      */
-    public boolean isHidden();      
+    public boolean isHidden();
+    
     /**
      * Returns true if the application can read this file.
      */
     public boolean canRead();
+    
     /**
      * Returns true if the application can write to this file.
      */
@@ -209,14 +244,17 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * Returns true if this folder or file actually exists.
      */
     public boolean exists();
+    
     /**
      * Returns the time (in milliseconds since epoch) this file was last modified.
      */
     public long getLastModified();
+    
 	/**
 	 * Return the last modified time as a Date object.
 	 */
 	public Date getLastModifiedDate() ;
+	
     /**
      * Returns the length, in bytes, of this file.
      */