Explain how to migrate to JSDoc 3

[hegemonic]

To a large extent, JSDoc 3's code markup is compatible with JsDoc Toolkit 2.4.0. But there are differences that often take people by surprise, including but certainly not limited to:

• Many tags that were required in JsDoc Toolkit 2.4.0 are not needed and shouldn't be used in JSDoc 3.
• JSDoc 3 won't process files that are not valid JavaScript. Also, if you're trying to use JSDoc for non-JavaScript files, you need to enable a plugin instead of passing in a command-line option.
• The module pattern is fully supported in JSDoc 3.
• Inner functions are included in the generated docs.

Another notable difference is that JSDoc 3 templates and plugins are not compatible with 2.4.0, and vice-versa.

For all of these reasons, it would be extremely useful to create a migration guide for users who want to move from 2.4.0.

I was prompted to file this by the discussion in jsdoc3/jsdoc#314.

[mauritslamers]

I am currently working on migrating to jsdoc3 from jsdoc toolkit 2.4.0n, I documented a few patterns (and a few questions about them) on SO: http://stackoverflow.com/questions/30232435/jsdoc3-migration-questions