jsdoc3/jsdoc — pull request #808 by theasta (2014-11-18 04:16:09+00:00)
Title: Facilate templates creation and maintenance

While working on a template that will not only generate html but also a docset, I realized two things:

* publish.js contains far too much code, related both to the view and to application logic. It is also extremely harsh to understand what's going on.
* the most popular themes (docstrap, jaguar) are not up to date and don't incorporate fixes and improvements added to the classic theme (for example interfaces or changes to the signature methods, the addition of … etc..)

I decided to create a class called TemplateRenderer and break down the different steps into methods easier to grasp. This way, when you create a theme, you only need to override the steps you want to change.

You can see how the jaguar template would look like once refactored using the TemplateRenderer:
https://github.com/theasta/jaguarjs-jsdoc/compare/publish-refactor?expand=1

or docstrap:
https://github.com/theasta/docstrap/compare/terryweiss:master...theasta:publish-refactor?expand=1

Much smaller! (In the examples, I'm overriding the prototype methods directly. It would probably preferable but more complex to first inherit from the TemplateRenderer and then override the methods.)

I also created a docletHelper similar to the templateHelper but only with functions taking a doclet as a parameter. It could probably be added to the templateHelper. I tried as much as possible not to modify existing files, except for publish.js.

The refactor is minor, I didn't want the code to suddently look unfamiliar to JSDoc main contributors. The only function I really changed is buildNav. It now returns an object that is going to be passed to a new template: navigation.html.
I made that change because navigation is what really differs between templates. This and signatures rendering that unfortunately at this point is still happening in the javascript code.

There is still room for improvement but I want to make sure first you are interested by this refactoring. Let me know what you think.

One last thing: since there are no tests for the templates, I used the following methodology to make sure I was not breaking anything:
* First, I gathered almost the jsdoc examples from the website.
* Then I rendered the documentation from the master branch.
* Then I rendered the documentation for the same codebase from my branch.
* I compared the result: there was no difference (apart from the timestamp in the footer of course)

I've also ran the tests and had an issue with eslint and the new keyword. I didn't really get why this rule exists since new is used in many other files. I had to disable this rule for publish.js as a quick fix. I'd love to get your feedback on that.