diff --git a/src/plugins/file.ts b/src/plugins/file.ts
index 4ec1f1e64..3bea03c61 100644
--- a/src/plugins/file.ts
+++ b/src/plugins/file.ts
@@ -341,6 +341,17 @@ declare var FileError: {
  * @description
  * This plugin implements a File API allowing read/write access to files residing on the device.
  *
+ * The File class implements static convenience functions to access files and directories.
+ *
+ * Example:
+ * ```
+ * import { File } from 'ionic-native';
+ *
+ * declare var cordova: any;
+ * const fs:string = cordova.file.dataDirectory;
+ * File.checkDir(this.fs, 'mydir').then(_ => console.log('yay')).catch(err => console.log('boooh'));
+ * ```
+ *
  *  This plugin is based on several specs, including : The HTML5 File API http://www.w3.org/TR/FileAPI/
  *  The (now-defunct) Directories and System extensions Latest: http://www.w3.org/TR/2012/WD-file-system-api-20120417/
  *  Although most of the plugin code was written when an earlier spec was current: http://www.w3.org/TR/2011/WD-file-system-api-20110419/
@@ -379,14 +390,14 @@ export class File {
    *
    * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} dir Name of directory to check
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<boolean|FileError>} Returns a Promise that resolves to true if the directory exists or rejects with an error.
    */
 
-  static checkDir(path: string, dir: string): Promise<boolean> {
+  static checkDir(path: string, dir: string): Promise<boolean|FileError> {
     if ((/^\//.test(dir))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<boolean>(err);
+      return Promise.reject<FileError>(err);
     }
 
     let fullpath = path + dir;
@@ -404,14 +415,14 @@ export class File {
    * @param {string} path  Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} dirName Name of directory to create
    * @param {boolean} replace If true, replaces file with same name. If false returns error
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<DirectoryEntry|FileError>} Returns a Promise that resolves with a DirectoryEntry or rejects with an error.
    */
 
-  static createDir(path: string, dirName: string, replace: boolean): Promise<DirectoryEntry> {
+  static createDir(path: string, dirName: string, replace: boolean): Promise<DirectoryEntry|FileError> {
     if ((/^\//.test(dirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<DirectoryEntry>(err);
+      return Promise.reject<FileError>(err);
     }
 
     let options: Flags = {
@@ -433,14 +444,14 @@ export class File {
    *
    * @param {string} path The path to the directory
    * @param {string} dirName The directory name
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<RemoveResult|FileError>} Returns a Promise that resolves to a RemoveResult or rejects with an error.
    */
 
-  static removeDir(path: string, dirName: string): Promise<RemoveResult> {
+  static removeDir(path: string, dirName: string): Promise<RemoveResult|FileError> {
     if ((/^\//.test(dirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<RemoveResult>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -459,16 +470,16 @@ export class File {
    * @param {string} dirName The source directory name
    * @param {string} newPath The destionation path to the directory
    * @param {string} newDirName The destination directory name
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<DirectoryEntry|FileError>} Returns a Promise that resolves to the new DirectoryEntry object or rejects with an error.
    */
 
-  static moveDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<DirectoryEntry> {
+  static moveDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<DirectoryEntry|FileError> {
     newDirName = newDirName || dirName;
 
     if ((/^\//.test(newDirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject<DirectoryEntry>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)
@@ -490,13 +501,13 @@ export class File {
    * @param {string} dirName Name of directory to copy
    * @param {string} newPath Base FileSystem of new location
    * @param {string} newDirName New name of directory to copy to (leave blank to remain the same)
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<Entry|FileError>} Returns a Promise that resolves to the new Entry object or rejects with an error.
    */
-  static copyDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<any> {
+  static copyDir(path: string, dirName: string, newPath: string, newDirName: string): Promise<Entry|FileError> {
     if ((/^\//.test(newDirName))) {
       let err = new FileError(5);
       err.message = 'directory cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)
@@ -516,7 +527,7 @@ export class File {
    *
    * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} dirName Name of directory
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<Entry[]>} Returns a Promise that resolves to an array of Entry objects or rejects with an error.
    */
 
   static listDir(path: string, dirName: string): Promise<Entry[]> {
@@ -541,7 +552,7 @@ export class File {
    *
    * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} dirName Name of directory
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<RemoveResult>} Returns a Promise that resolves with a RemoveResult or rejects with an error.
    */
 
   static removeRecursively(path: string, dirName: string): Promise<RemoveResult> {
@@ -565,14 +576,14 @@ export class File {
    *
    * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} file Name of file to check
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<boolean|FileError>} Returns a Promise that resolves with a boolean or rejects with an error.
    */
 
-   static checkFile(path: string, file: string): Promise<boolean> {
+  static checkFile(path: string, file: string): Promise<boolean|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file cannot start with \/';
-      return Promise.reject<boolean>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveLocalFilesystemUrl(path + file)
@@ -595,13 +606,13 @@ export class File {
    * @param {string} path  Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} fileName Name of file to create
    * @param {boolean} replace If true, replaces file with same name. If false returns error
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<FileEntry|FileError>} Returns a Promise that resolves to a FileEntry or rejects with an error.
    */
-  static createFile(path: string, fileName: string, replace: boolean): Promise<any> {
+  static createFile(path: string, fileName: string, replace: boolean): Promise<FileEntry|FileError> {
     if ((/^\//.test(fileName))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     let options: Flags = {
@@ -623,14 +634,14 @@ export class File {
    *
    * @param {string} path  Base FileSystem. Please refer to the iOS and Android filesystems above
    * @param {string} fileName Name of file to remove
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<RemoveResult|FileError>} Returns a Promise that resolves to a RemoveResult or rejects with an error.
    */
 
-  static removeFile(path: string, fileName: string): Promise<RemoveResult> {
+  static removeFile(path: string, fileName: string): Promise<RemoveResult|FileError> {
     if ((/^\//.test(fileName))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<RemoveResult>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -642,6 +653,14 @@ export class File {
       });
   }
 
+  /** Write a new file to the desired location.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName path relative to base path
+   * @param {string} text content to write
+   * @param {boolean | WriteOptions} replaceOrOptions replace file if set to true. See WriteOptions for more information.
+   * @returns {Promise<void>} Returns a Promise that resolves or rejects with an error.
+   */
   static writeFile(path: string, fileName: string,
                    text: string, replaceOrOptions: boolean | WriteOptions): Promise<void> {
     if ((/^\//.test(fileName))) {
@@ -681,6 +700,13 @@ export class File {
       });
   }
 
+  /** Write to an existing file.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} fileName path relative to base path
+   * @param {string} text content to write
+   * @returns {Promise<void>} Returns a Promise that resolves or rejects with an error.
+   */
   static writeExistingFile(path: string, fileName: string, text: string): Promise<void> {
     if ((/^\//.test(fileName))) {
       let err = new FileError(5);
@@ -700,11 +726,18 @@ export class File {
       });
   }
 
-  static readAsText(path: string, file: string): Promise<string> {
+  /**
+   * Read the contents of a file as text.
+   *
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<string|FileError>} Returns a Promise that resolves with the contents of the file as string or rejects with an error.
+   */
+  static readAsText(path: string, file: string): Promise<string|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<string>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -728,12 +761,20 @@ export class File {
         });
       });
   }
+  /**
+   * Read file and return data as a base64 encoded data url.
+   * A data url is of the form:
+   *      data:[<mediatype>][;base64],<data>
 
-  static readAsDataURL(path: string, file: string): Promise<string> {
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<string|FileError>} Returns a Promise that resolves with the contents of the file as data URL or rejects with an error.
+   */
+  static readAsDataURL(path: string, file: string): Promise<string|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<string>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -758,11 +799,18 @@ export class File {
       });
   }
 
-  static readAsBinaryString(path: string, file: string): Promise<string> {
+  /**
+   * Read file and return data as a binary data.
+
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<string|FileError>} Returns a Promise that resolves with the contents of the file as string rejects with an error.
+   */
+  static readAsBinaryString(path: string, file: string): Promise<string|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<string>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -787,11 +835,18 @@ export class File {
       });
   }
 
-  static readAsArrayBuffer(path: string, file: string): Promise<ArrayBuffer> {
+  /**
+   * Read file and return data as an ArrayBuffer.
+
+   * @param {string} path Base FileSystem. Please refer to the iOS and Android filesystems above
+   * @param {string} file Name of file, relative to path.
+   * @return {Promise<ArrayBuffer|FileError>} Returns a Promise that resolves with the contents of the file as ArrayBuffer or rejects with an error.
+   */
+  static readAsArrayBuffer(path: string, file: string): Promise<ArrayBuffer|FileError> {
     if ((/^\//.test(file))) {
       let err = new FileError(5);
       err.message = 'file-name cannot start with \/';
-      return Promise.reject<ArrayBuffer>(err);
+      return Promise.reject<FileError>(err);
     }
 
     return File.resolveDirectoryUrl(path)
@@ -823,15 +878,15 @@ export class File {
    * @param {string} fileName Name of file to move
    * @param {string} newPath Base FileSystem of new location
    * @param {string} newFileName New name of file to move to (leave blank to remain the same)
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<Entry|FileError>} Returns a Promise that resolves to the new Entry or rejects with an error.
    */
-  static moveFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> {
+  static moveFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<Entry|FileError> {
     newFileName = newFileName || fileName;
 
     if ((/^\//.test(newFileName))) {
       let err = new FileError(5);
       err.message = 'file name cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)
@@ -853,15 +908,15 @@ export class File {
    * @param {string} fileName Name of file to copy
    * @param {string} newPath Base FileSystem of new location
    * @param {string} newFileName New name of file to copy to (leave blank to remain the same)
-   * @return Returns a Promise that resolves or rejects with an error.
+   * @return {Promise<Entry|FileError>} Returns a Promise that resolves to an Entry or rejects with an error.
    */
-  static copyFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<any> {
+  static copyFile(path: string, fileName: string, newPath: string, newFileName: string): Promise<Entry|FileError> {
     newFileName = newFileName || fileName;
 
     if ((/^\//.test(newFileName))) {
       let err = new FileError(5);
       err.message = 'file name cannot start with \/';
-      return Promise.reject(err);
+      return Promise.reject<FileError>(err);
     }
 
     return this.resolveDirectoryUrl(path)