Add IStorageProvider interface, add some documentation

Going to be going heavily over documentation in the next few days so I can get this storage rewrite merged reasonably and start on other changes prior to release

src/index.ts

@@ -12,6 +12,7 @@ export { Middleware } from './lib/command/middleware/Middleware';
 export { RateLimit } from './lib/command/RateLimit';
 export { RateLimiter } from './lib/command/RateLimiter';
 
+export { IStorageProvider } from './lib/storage/interface/IStorageProvider';
 export { StorageProvider } from './lib/storage/StorageProvider';
 export { StorageFactory } from './lib/storage/StorageFactory';
 export { JSONProvider } from './lib/storage/JSONProvider';

src/lib/bot/Bot.ts

@@ -304,7 +304,7 @@ export class Bot extends Client
 	 * @memberof Bot
 	 * @instance
 	 * @param {string} key - The key to use in settings storage
-	 * @returns {Bot}
+	 * @returns {Promise<Bot>}
 	 */
 	public async removeDefaultSetting(key: string): Promise<this>
 	{
@@ -317,7 +317,7 @@ export class Bot extends Client
 	 * @memberof Bot
 	 * @instance
 	 * @param {string} key - The key in storage to check
-	 * @returns {boolean}
+	 * @returns {Promise<boolean>}
 	 */
 	public async defaultSettingExists(key: string): Promise<boolean>
 	{
@@ -329,7 +329,7 @@ export class Bot extends Client
 	 * @memberof Bot
 	 * @instance
 	 * @param {(external:Guild|string)} guild The guild or guild id to get the prefix of
-	 * @returns {string|null}
+	 * @returns {Promise<?string>}
 	 */
 	public async getPrefix(guild: Guild): Promise<string>
 	{

src/lib/command/middleware/Middleware.ts

@@ -25,11 +25,12 @@ export class Middleware
 	 * </code></pre><br>
 	 *
 	 * Supports <code>'...'</code> in the argument name as the final argument to
-	 * gather the remaining args into one string
+	 * gather all remaining words into one string and attempt to resolve them to
+	 * the provided argument type
 	 * @name resolveArgs
 	 * @method
 	 * @memberof Middleware
-	 * @param {object} argTypes An object of argument names mapped to argument types
+	 * @param {object} argTypes An object of argument names mapped to argument types<br>
 	 * 							See: {@link ResolveArgType}
 	 * @returns {Function} <pre class="prettyprint"><code>(message: Message, args: any[]) => [Message, any[]]</code></pre>
 	 */
@@ -57,7 +58,7 @@ export class Middleware
 	 * @name expect
 	 * @method
 	 * @memberof Middleware
-	 * @param {object} argTypes An object of argument names mapped to argument types
+	 * @param {object} argTypes An object of argument names mapped to argument types<br>
 	 * 							See: {@link ExpectArgType}
 	 * @returns {Function} <pre class="prettyprint"><code>(message: Message, args: any[]) => [Message, any[]]</code></pre>
 	 */

src/lib/storage/JSONProvider.ts

@@ -1,7 +1,15 @@
+import { IStorageProvider } from './interface/IStorageProvider';
 import { StorageProvider } from './StorageProvider';
 import DB = require('node-json-db');
 
-export class JSONProvider extends StorageProvider
+/**
+ * Default storage provider for the framework. If no storage provider is passed
+ * in the client constructor, this provider will be used
+ * @class JSONProvider
+ * @extends StorageProvider
+ * @implements IStorageProvider
+ */
+export class JSONProvider extends StorageProvider implements IStorageProvider
 {
 	private _name: string;
 	private _db: DB;

src/lib/storage/StorageProvider.ts

@@ -1,4 +1,28 @@
-export class StorageProvider
+import { IStorageProvider } from './interface/IStorageProvider';
+
+/**
+ * Abstract class for storage providers to extend. Provides runtime errors
+ * for missing method implementations, and is necessary at compile-time
+ * for the compiler to recognize a StorageProvider as valid.
+ * <br><br>
+ * StorageProviders must present an interface with a storage solution that
+ * provides access to string values via string keys. Data will be stored
+ * in the storage solution by the framework as stringified JSON-valid data
+ * <br><br>
+ * <b>Note:</b> All methods shown on this class must be implemented within
+ * any storage providers you create and, in the case of <code>keys()</code>
+ * and <code>get()</code>, <b>must</b> return the proper data types or your
+ * client <b>will not work</b>.
+ * @abstract
+ * @class StorageProvider
+ * @implements IStorageProvider
+ * @param {string} name Name of the storage to access. Can be a DB table, file name, etc. Whatever the storage solution expects
+ *						with regards to providing a unique identifier for a specific storage.<br><br><b>Note:</b> This does not need to be
+ *						passed to <code>super()</code> in classes extending <code>StorageProvider</code> as <code>StorageProvider</code>
+ *						is abstract and provides no implementation, but should be received by and used within your storage provider
+ *						constructors as necessary to create a unique storage based on the given string
+ */
+export class StorageProvider implements IStorageProvider
 {
 	public async init(): Promise<void> { throw new Error('Storage providers must implement the `init` method'); }
 	public async keys(): Promise<string[]> { throw new Error('Storage providers must implement the `keys` method'); }

src/lib/storage/interface/IStorageProvider.ts

@@ -0,0 +1,61 @@
+/**
+ * Interface for storage providers to implement, providing compile-time
+ * errors for incorrect implementations alongside the abstract StorageProvider
+ * class to extend which provides runtime errors for missing method implementations
+ * <br><br>
+ * <b>Note:</b> This is a TypeScript feature and you do not need to worry about this bit so much
+ * if you are using JavaScript.
+ * @interface IStorageProvider
+ */
+/**
+ * Async method to be run that will set up the storage provider
+ * for use. Calls to other provider methods should not be made
+ * until this method has been called and resolved
+ * @name IStorageProvider#init
+ * @method
+ * @returns {Promise<void>}
+ */
+/**
+ * Async method returning an array of stored key names
+ * @name IStorageProvider#keys
+ * @method
+ * @returns {Promise<string[]>}
+ */
+/**
+ * Async method that gets the value of a key in storage
+ * @name IStorageProvider#get
+ * @method
+ * @param {string} key The name of the key in storage
+ * @returns {Promise<string>}
+ */
+/**
+ * Async method that sets the value of a key in storage
+ * @name IStorageProvider#set
+ * @method
+ * @param {string} key The name of the key in storage
+ * @param {string} value The value to set in storage
+ * @returns {Promise<void>}
+ */
+/**
+ * Async method that removes a key and its value from storage
+ * @name IStorageProvider#remove
+ * @method
+ * @param {string} key The name of the key in storage
+ * @returns {Promise<void>}
+ */
+/**
+ * Async method that removes all keys and their values from storage
+ * @name IStorageProvider#clear
+ * @method
+ * @returns {Promise<void>}
+ */
+
+export interface IStorageProvider
+{
+	init(): Promise<void>;
+	keys(): Promise<string[]>;
+	get(key: string): Promise<string>;
+	set(key: string, value: string): Promise<void>;
+	remove(key: string): Promise<void>;
+	clear(): Promise<void>;
+}