JsDoc fixes for issue #11

[kristiancalhoun]

Reintroduce @exports tag to document modules.
Switch from @name to @alias to document object properties.
Added some @defaults to CentralBody.
@enumerations no longer list 'new' in their documentation as though they were a class.

[pjcozzi]

A few comments/questions:

• The doc is still missing all the GLSL functions. Is that because they are in .glsl files? Should that be fixed with this pull request?
• On the main doc page, should switching between all, js, and glsl clear the filter?
• Did we switch to var foo = function... to workaround a jsdoc-toolkit bug? If so, did we tell them?
• I find the use of both @exports and @alias verbose, but if that is how it has to be, it is OK with me.

[kristiancalhoun]

The doc is still missing all the GLSL functions. Is that because they are in .glsl files? Should that be fixed with this pull request?

Yes, it is. I tried changing the JsDoc configuration file to read .glsl files as well as .js files, but JsDoc chokes on the different syntax. @shunter, do you have any ideas? Is stripping out the comments during the build process and writing them to another file for JsDoc to read unreasonable?

On the main doc page, should switching between all, js, and glsl clear the filter?
Yup, that would definitely improve usability.

Did we switch to var foo = function... to workaround a jsdoc-toolkit bug? If so, did we tell them?

Not so much a bug as the design of JsDoc. The problem is that function foo() is within an anonymous function inside of the module definition, so JsDoc won't document it. We previously got around this problem by using the @name tag, which basically tells JsDoc to just look at the comment and not the code. However, then documentation for the inner properties is not generated (using '@constructor foo' has the same problem). var foo = function is the recommended way to document classes within modules as seen here : http://usejsdoc.org/howto-commonjs-modules.html.

If you're interested in reading more: https://groups.google.com/forum/?fromgroups#!searchin/jsdoc-users/function$20Sample/jsdoc-users/L1n50YvtwFY/aB2gVbxD4RwJ

I find the use of both @exports and @alias verbose, but if that is how it has to be, it is OK with me.
You're right. I'll cut out the @exports where @alias is present.

[pjcozzi]

@kristiancalhoun let us know when this is ready for review again.

[kristiancalhoun]

It's good to go.

[pjcozzi]

I still don't see any GLSL functions. Do I need to clean build?

[kristiancalhoun]

Yeah, try that. I just did another clean build and it worked for me.

[pjcozzi]

Can you please tweak a few minor things:

• agi_emptyRaySegment shows up twice - http://localhost:8080/Build/Documentation/agi_emptyRaySegment.html. Can you track down where it is duplicated? Same for agi_complement and agi_insertAt.
• agi_intersection results in a HTTP 404 error - http://localhost:8080/Build/Documentation/global.html#agi_intersection

[kristiancalhoun]

agi_emptyRaySegment is duplicated in BuiltinFunctions.glsl. It looks to be a copy/paste error, as one should be agi_fullRaySegment.

@agi_complement, @agi_insertAt, and @agi_intersection are duplicated because they're overloaded functions and each is tagged.

[pjcozzi]

OK. Can you fix them? Should be trivial.

[kristiancalhoun]

Alright, 5055141 takes care of those issues.

[pjcozzi]

agi_complement, agi_insertAt, and agi_intersection all return an HTTP error.

[kristiancalhoun]

Interseting. They all work for me from both the index page and sidebar. Did you try another clean build? What is the broken URL for each?

[pjcozzi]

Yes, I cleaned. It is probably because I am using the filter: http://localhost:8080/Build/Documentation/global.html?classFilter=agi_com#agi_complement.

[kristiancalhoun]

global.html is purposefully not generated (because nothing should link there), which is why you're getting an error. I searched through my entire documentation folder and couldn't find anything that linked to global.html. Regardless, sync up and try again with this latest commit.

[pjcozzi]

Looks good now.

@mramato I suppose you'll want to pull master in to get this.