fix(sqlite): resolve race condition, add comments (#235)

src/plugins/sqlite.ts

@@ -2,6 +2,30 @@ import {CordovaInstance, Plugin, Cordova} from './plugin';
 declare var sqlitePlugin;
 /**
  * @name SQLite
+ *
+ * @description
+ * Access SQLite databases on the device.
+ *
+ * @usage
+ *
+ * ```ts
+ * import { SQLite } from 'ionic-native';
+ *
+ * let db = new SQLite();
+ * db.openDatabse({
+ *   name: 'data.db',
+ *   location: 'default' // the location field is required
+ * }).then(() => {
+ *   db.executeSql('create table danceMoves(name VARCHAR(32))', {}).then(() => {
+ *
+ *   }, (err) => {
+ *     console.error('Unable to execute sql', err);
+ *   })
+ * }, (err) => {
+ *   console.error('Unable to open database', err);
+ * });
+ * ```
+ *
  */
 @Plugin({
     pluginRef: 'sqlitePlugin',
@@ -15,13 +39,44 @@ export class SQLite {
         return this._objectInstance.databaseFeatures;
     }
 
-    constructor (config: any) {
-       new Promise((resolve, reject) => {
-           sqlitePlugin.openDatabase(config, resolve, reject);
-       }).then(
-           db => this._objectInstance = db,
-           error => console.warn(error)
-       );
+    constructor () {}
+
+    /**
+     * Open or create a SQLite database file.
+     *
+     * See the plugin docs for an explanation of all options: https://github.com/litehelpers/Cordova-sqlite-storage#opening-a-database
+     *
+     * @param config the config for opening the database.
+     * @usage
+     *
+     * ```ts
+     * import { SQLite } from 'ionic-native';
+     *
+     * let db = new SQLite();
+     * db.openDatabse({
+     *   name: 'data.db',
+     *   location: 'default' // the location field is required
+     * }).then(() => {
+     *   db.executeSql('create table danceMoves(name VARCHAR(32))', {}).then(() => {
+     *
+     *   }, (err) => {
+     *     console.error('Unable to execute sql', err);
+     *   })
+     * }, (err) => {
+     *   console.error('Unable to open database', err);
+     * });
+     * ```
+     */
+    openDatabase (config: any) : Promise<any> {
+      return new Promise((resolve, reject) => {
+          sqlitePlugin.openDatabase(config, db => {
+              this._objectInstance = db;
+              resolve(db);
+          }, error => {
+              console.warn(error)
+              reject(error);
+          });
+      });
     }
 
     @CordovaInstance({
@@ -48,6 +103,19 @@ export class SQLite {
     })
     start (): void {}
 
+    /**
+     * Execute SQL on the opened database. Note, you must call `openDatabase` first, and
+     * ensure it resolved and successfully opened the database.
+     *
+     * @usage
+     *
+     * ```ts
+     * db.executeSql('SELECT FROM puppies WHERE type = ?', ['cavalier']).then((resultSet) => {
+     *   // Access the items through resultSet.rows
+     *   // resultSet.rows.item(i)
+     * }, (err) => {})
+     * ```
+     */
     @CordovaInstance()
     executeSql (statement: string, params: any): Promise<any> {return; }
 
@@ -104,4 +172,4 @@ export class SQLite {
     @Cordova()
     static deleteDatabase (first): Promise<any> {return; }
 
-}
+}