Fix API documentation

docs/API.md

@@ -22,7 +22,7 @@ Loads a document at the provided location and returns a JavaScript object repres
 
 | Param | Type | Description |
 | --- | --- | --- |
-| location | <code>LoadOptions</code> | The location to the document |
+| location | <code>[LoadOptions](#module_path-loader..LoadOptions)</code> | The location to the document |
 
 **Example**  
 ```js
@@ -96,8 +96,8 @@ Options used when loading a path.
 | --- | --- | --- | --- |
 | encoding | <code>string</code> | <code>&quot;&#x27;utf-8&#x27;&quot;</code> | The encoding to use when loading the file *(File loader only)* |
 | method | <code>string</code> | <code>&quot;get&quot;</code> | The HTTP method to use for the request *(HTTP loader only)* |
-| prepareRequest | <code>PrepareRequestCallback</code> |  | The callback used to prepare the request *(HTTP loader only)* |
-| processContent | <code>ProcessResponseCallback</code> |  | The callback used to process the response |
+| prepareRequest | <code>[PrepareRequestCallback](#module_path-loader..PrepareRequestCallback)</code> |  | The callback used to prepare the request *(HTTP loader only)* |
+| processContent | <code>[ProcessResponseCallback](#module_path-loader..ProcessResponseCallback)</code> |  | The callback used to process the response |
 
 <a name="module_path-loader..PrepareRequestCallback"></a>
 

gulpfile.js

@@ -93,16 +93,18 @@ gulp.task('clean', function (done) {
 
 gulp.task('docs', function () {
   return gulp.src([
-    './index.js'
+    './index.js',
+    './lib/typedefs.js'
   ])
     .pipe($.concat('API.md'))
     .pipe($.jsdoc2MD())
     .pipe(gulp.dest('docs'));
 });
 
-gulp.task('docs-ts', function (cb) {
+gulp.task('docs-ts-raw', function (cb) {
   gulp.src([
-    './index.js'
+    './index.js',
+    './lib/typedefs.js'
   ])
     .pipe($.jsdoc3({
       opts: {
@@ -112,6 +114,17 @@ gulp.task('docs-ts', function (cb) {
     }, cb));
 });
 
+// Due to bugs in @otris/jsdoc-tsd, we need to "fix" the generated TSD.
+//
+//  * https://github.com/otris/jsdoc-tsd/issues/38
+//  * https://github.com/otris/jsdoc-tsd/issues/39
+gulp.task('docs-ts', ['docs-ts-raw'], function () {
+  gulp.src(['index.d.ts'])
+    .pipe($.replace('<*>', '<any>'))
+    .pipe($.replace('module:path-loader~', ''))
+    .pipe(gulp.dest('.'));
+});
+
 gulp.task('lint', function () {
   return gulp.src([
       'lib/**/*.js',

index.d.ts

@@ -3,51 +3,51 @@
  */
 declare module 'path-loader' {
     /**
-     * Options used when loading a path.
+     * Loads a document at the provided location and returns a JavaScript object representation.
+     * @param location - The location to the document
+     * @returns Always returns a promise even if there is a callback provided
      */
-    declare interface LoadOptions {
-        /**
-         * The encoding to use when loading the file *(File loader only)*
-         */
-        encoding?: string;
-        /**
-         * The HTTP method to use for the request *(HTTP loader only)*
-         */
-        method?: string;
-        /**
-         * The callback used to prepare the request *(HTTP loader only)*
-         */
-        prepareRequest?: PrepareRequestCallback;
-        /**
-         * The callback used to process the response
-         */
-        processContent?: ProcessResponseCallback;
-    }
+    export function load(location: LoadOptions): Promise.<any>;
 
+}
+
+/**
+ * Options used when loading a path.
+ */
+declare interface LoadOptions {
     /**
-     * Callback used to provide access to altering a remote request prior to the request being made.
-     * @param req - The Superagent request object
-     * @param location - The location being retrieved
-     * @param callback - First callback
+     * The encoding to use when loading the file *(File loader only)*
      */
-    declare type PrepareRequestCallback = (req: object, location: string, callback: Function)=>void;
-
+    encoding?: string;
     /**
-     * Callback used to provide access to processing the raw response of the request being made. *(HTTP loader only)*
-     * @param res - The Superagent response object *(For non-HTTP loaders, this object will be like the Superagent
-     *        object in that it will have a `text` property whose value is the raw string value being processed.  This was done
-     *        for consistency.)*
-     * @param callback - Error-first callback
-     * @returns the result of processing the responsexs
+     * The HTTP method to use for the request *(HTTP loader only)*
      */
-    declare type ProcessResponseCallback = (res: object, callback: Function)=>any;
-
+    method?: string;
     /**
-     * Loads a document at the provided location and returns a JavaScript object representation.
-     * @param location - The location to the document
-     * @returns Always returns a promise even if there is a callback provided
+     * The callback used to prepare the request *(HTTP loader only)*
      */
-    export function load(location: LoadOptions): Promise<any>;
-
+    prepareRequest?: PrepareRequestCallback;
+    /**
+     * The callback used to process the response
+     */
+    processContent?: ProcessResponseCallback;
 }
 
+/**
+ * Callback used to provide access to altering a remote request prior to the request being made.
+ * @param req - The Superagent request object
+ * @param location - The location being retrieved
+ * @param callback - First callback
+ */
+declare type PrepareRequestCallback = (req: object, location: string, callback: Function)=>void;
+
+/**
+ * Callback used to provide access to processing the raw response of the request being made. *(HTTP loader only)*
+ * @param res - The Superagent response object *(For non-HTTP loaders, this object will be like the Superagent
+ *        object in that it will have a `text` property whose value is the raw string value being processed.  This was done
+ *        for consistency.)*
+ * @param callback - Error-first callback
+ * @returns the result of processing the responsexs
+ */
+declare type ProcessResponseCallback = (res: object, callback: Function)=>any;
+

index.js

@@ -53,40 +53,6 @@ function getScheme (location) {
  * @module path-loader
  */
 
-/**
- * Options used when loading a path.
- *
- * @typedef {object} LoadOptions
- *
- * @property {string} [encoding='utf-8'] - The encoding to use when loading the file *(File loader only)*
- * @property {string} [method=get] - The HTTP method to use for the request *(HTTP loader only)*
- * @property {PrepareRequestCallback} [prepareRequest] - The callback used to prepare the request *(HTTP loader only)*
- * @property {ProcessResponseCallback} [processContent] - The callback used to process the response
- */
-
-/**
- * Callback used to provide access to altering a remote request prior to the request being made.
- *
- * @callback PrepareRequestCallback
- *
- * @param {object} req - The Superagent request object
- * @param {string} location - The location being retrieved
- * @param {function} callback - First callback
- */
-
- /**
-  * Callback used to provide access to processing the raw response of the request being made. *(HTTP loader only)*
-  *
-  * @callback ProcessResponseCallback
-  *
-  * @param {object} res - The Superagent response object *(For non-HTTP loaders, this object will be like the Superagent
-  * object in that it will have a `text` property whose value is the raw string value being processed.  This was done
-  * for consistency.)*
-  * @param {function} callback - Error-first callback
-  *
-  * @returns {*} the result of processing the responsexs
-  */
-
 function getLoader (location) {
   var scheme = getScheme(location);
   var loader = supportedLoaders[scheme];
@@ -105,7 +71,7 @@ function getLoader (location) {
 /**
  * Loads a document at the provided location and returns a JavaScript object representation.
  *
- * @param {LoadOptions} location - The location to the document
+ * @param {module:path-loader~LoadOptions} location - The location to the document
  *
  * @returns {Promise<*>} Always returns a promise even if there is a callback provided
  *

lib/typedefs.js

@@ -0,0 +1,37 @@
+/**
+ * This file contains all type definitions that are purely for documentation purposes.
+ */
+
+/**
+ * Options used when loading a path.
+ *
+ * @typedef {object} LoadOptions
+ *
+ * @property {string} [encoding='utf-8'] - The encoding to use when loading the file *(File loader only)*
+ * @property {string} [method=get] - The HTTP method to use for the request *(HTTP loader only)*
+ * @property {module:path-loader~PrepareRequestCallback} [prepareRequest] - The callback used to prepare the request *(HTTP loader only)*
+ * @property {module:path-loader~ProcessResponseCallback} [processContent] - The callback used to process the response
+ */
+
+/**
+ * Callback used to provide access to altering a remote request prior to the request being made.
+ *
+ * @callback PrepareRequestCallback
+ *
+ * @param {object} req - The Superagent request object
+ * @param {string} location - The location being retrieved
+ * @param {function} callback - First callback
+ */
+
+ /**
+  * Callback used to provide access to processing the raw response of the request being made. *(HTTP loader only)*
+  *
+  * @callback ProcessResponseCallback
+  *
+  * @param {object} res - The Superagent response object *(For non-HTTP loaders, this object will be like the Superagent
+  * object in that it will have a `text` property whose value is the raw string value being processed.  This was done
+  * for consistency.)*
+  * @param {function} callback - Error-first callback
+  *
+  * @returns {*} the result of processing the responsexs
+  */

package.json

@@ -49,6 +49,7 @@
     "gulp-load-plugins": "^1.5.0",
     "gulp-mocha": "~3.0.1",
     "gulp-nsp": "^2.4.2",
+    "gulp-replace": "^1.0.0",
     "gulp-uglify": "^3.0.0",
     "karma": "^1.6.0",
     "karma-mocha": "^1.3.0",