Use JSDoc (#317)

Clean up doc tags and move towards JSDoc

- name modules consistently following commonjs pathing
- fix missing types for some functions
- add missing blocks for some functions
- begin thinking about how to structure doc blocks to generate comprehensive
  overview of code surface

* Add a @SInCE 1.1.0 tag to setHeaders methods

* Wrap @example descriptions in <caption> tags

* Standardize on @returns in JSDoc blocks

* Remove YUIDoc and its references

* Switch inline documentation to JSDoc

Fixes #316

Author: kadamwhite

.jsdoc.json

@@ -0,0 +1,29 @@
+{
+	"source": {
+		"include": [
+			"lib",
+			"wpapi.js",
+			"wpapi-computed-methods.jsdoc",
+			"package.json",
+			"build/api-reference-readme.md"
+		],
+		"includePattern": ".+\\.js(doc)?$",
+		"excludePattern": "(browser/|bin/|build/|data/|tests/|node_modules)"
+	},
+	"plugins": [
+		"plugins/markdown"
+	],
+	"tags": {
+		"dictionaries": ["jsdoc"]
+	},
+	"templates": {
+		"useLongnameInNav": false,
+		"showInheritedInNav": true
+	},
+	"opts": {
+		"destination": "./documentation/api-reference/",
+		"template": "node_modules/minami",
+		"encoding": "utf8",
+		"recurse": true
+	}
+}

.npmignore

@@ -8,7 +8,6 @@ pids
 *.sublime-*
 _gh_issues/
 coverage
-docs-theme/
 docs-tmp/
 docs/
 index.html

CONTRIBUTING.md

@@ -111,11 +111,13 @@ We prefer `camelCase` variable and function names, and `UpperCamelCase` construc
 
 ## Documentation
 
-The README getting started guide & YUIDoc block comment should be kept up-to-date with feature development: If you aren't familiar with adding doc blocks, we'll help you work through it in the comments of your PR.
+The README getting started guide & [JSDoc](http://usejsdoc.org/) block comment should be kept up-to-date with featrbenvure development: If you aren't familiar with adding JSDoc comments, we'll help you work through it in the comments of your PR.
 
-The API docs will be updated whenever a new NPM module version is published. No files within `docs/` should be committed in any branch other than gh-pages.
+The API docs will be updated whenever a new NPM module version is published. No generated files within `documentation/` should be committed in any branch other than gh-pages.
 
-To generate the docs yourself, run `npm run docs` (aliased to `grunt yuidoc`).
+To generate the docs yourself, run `npm run docs`. This task will parse the README into a series of individual markdown files, then run JSDoc to generate the API reference. These files will be consumed by GitHub Pages to render the final public [wp-api.org/node-wpapi](http://wp-api.org/node-wpapi) website.
+
+Preview the generated documentation site locally with `npm run jekyll`. To install Jekyll you will need Ruby (v2.3.x is required due to a dependency issue in 2.4), then run `gem install bundler` and `bundle install` from the `documentation/` directory.
 
 ## Branch Naming & Pull Requests
 
@@ -127,7 +129,11 @@ Internally, we try to use the following branch naming scheme to keep things orga
 * **build/feature-name**: Features relating to the build process, Gruntfile, linting or testing process, NPM package, *etcetera*
 * **docs/feature-name**: Documentation, README, contributing guide, fleshing out inline doc blocks; anything in the repository that's authored to be human-readable
 
-It is not essential to maintain this naming structure in your own branches, though it is preferred; the important thing is that pull requests *not* be submitted from your master branch.
+It is not essential to maintain this naming structure in your own branches; the important thing is that pull requests *not* be submitted from your master branch.
+
+## Release "Props"
+
+Code is only a small part of the effort that goes into maintaining an open source project. We recognize both code _and_ non-code contributions with release "props," celebrating those who devote time and energy to the `wpapi` package. If you open an issue that highlights a bug, or contribute documentation and user guides, you will receive recognition for your support in the release notes where the associated code or documentation changes appear. Please participate constructively in [issue](https://github.com/wp-api/node-wpapi/issues) discussions, and thank you for your support!
 
 ## License
 

Gruntfile.js

@@ -16,7 +16,6 @@ module.exports = function( grunt ) {
 	grunt.registerTask( 'docs', [
 		'clean',
 		'generate_readme_docs',
-		'zip',
-		'yuidoc'
+		'zip'
 	]);
 };

README.md

@@ -928,7 +928,7 @@ var wp = new WPAPI({
 
 ## API Documentation
 
-In addition to the above getting-started guide, we have automatically-generated [API documentation](http://wp-api.github.io/node-wpapi).
+In addition to the above getting-started guide, we have automatically-generated [API documentation](http://wp-api.github.io/node-wpapi/api-reference/).
 
 
 ## Issues

build/api-reference-readme.md

@@ -0,0 +1,7 @@
+## WPAPI Code Reference
+
+Welcome to the API Reference for the `wpapi` NPM package.
+
+Running `require( 'wpapi' )` returns the `WPAPI` constructor, which you can read about by clicking its name in the class list in the menu. Each request handler factory on `WPAPI` (such as `.posts()`, `.pages()`, _etc._) returns a `WPRequest` object, conditionally augmented with one or more mixins depending on the capabilities of the associated endpoints.
+
+For user guides & tutorials, visit [wp-api.org/node-wpapi/](http://wp-api.org/node-wpapi).

build/grunt/yuidoc.js

@@ -14,6 +14,9 @@ combyne.settings.delimiters = {
 	END_EXPR: '%}]'
 };
 
+// Application Version
+const version = require( '../../package.json' ).version;
+
 // Paths
 const projectRoot = path.join( __dirname, '../..' );
 const docsDir = path.join( projectRoot, 'documentation' );
@@ -170,7 +173,7 @@ const readmeOutput = readFile( readmePath ).then( contents => {
 	}, Promise.resolve() ).then( () => {
 		entries.push({
 			title: 'API Documentation',
-			slug: 'api-reference/modules/WPAPI.html'
+			slug: `api-reference/wpapi/${version}/`
 		});
 		return entries;
 	});