Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Upgrade JSDoc to 3.3.0-alpha 5 #1745

Merged
merged 6 commits into from
May 26, 2014
Merged

Upgrade JSDoc to 3.3.0-alpha 5 #1745

merged 6 commits into from
May 26, 2014

Conversation

shunter
Copy link
Contributor

@shunter shunter commented May 23, 2014

Note: this pull includes the changes from #1743 so merge that first.

This upgrades JSDoc from 3.0 to 3.3.0-alpha5, the latest available version. This version runs in Node instead of Rhino, and as a result, runs much faster.

I've build locally and deployed to

http://cesium.blob.core.windows.net/shunter-jsdoc-upgrade/index.html

so you can easily take a look.

To generate documentation, you must install NodeJS and run npm install in the Cesium directory to install JSDoc from npm. Once this goes in, I'll update the contributor's guide.

Due to our previous heavy hackery of the JSDoc source, I rewrote the template to apply our desired customizations without needing changes to JSDoc. Along the way, I changed basically everything about the HTML, including formatting changes. I'm open to revisions. I based the template on the default, but at this point we "own" the code in there now, to change as we see fit.

As per @pjcozzi, I dropped support for documenting GLSL.

Fixes #1687

@shunter
Copy link
Contributor Author

shunter commented May 23, 2014

I based some of the styling on this template : https://github.com/davidshimjs/jaguarjs-jsdoc

If you're curious what that looks like stock, I generated with that template and uploaded here:

http://cesium.blob.core.windows.net/shunter-jsdoc-upgrade/Jaguar/index.html

The main problem with this template is that because the nav bar contains all members of all classes, each and every HTML page is over 500KB (!)

Still, you may find it interesting to see another style.

@pjcozzi
Copy link
Contributor

pjcozzi commented May 26, 2014

Doc build is now 47 seconds on my Mac.

@pjcozzi
Copy link
Contributor

pjcozzi commented May 26, 2014

Looks good. Remember to update the Contributor's Guide. If you are up for it, it could be a good time to rewrite the Documentation Best Practices guide, which would help with #1684.

pjcozzi added a commit that referenced this pull request May 26, 2014
@pjcozzi pjcozzi merged commit ecdbfee into master May 26, 2014
@pjcozzi pjcozzi deleted the jsDocUpgrade branch May 26, 2014 18:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Upgrade to JSDoc 3
2 participants