Documentation missing for stand-alone functions

[mramato]

For example, createGuid and binarySearch both have documentation, but it does not show up in the JSDoc tree.

[pjcozzi]

This includes GLSL functions like agi_rayEllipsoidIntersectionInterval.

[mramato]

It also appears that member variables don't show up properly either, if you force the doc with a memberof attribute, they will show up, but be marked as static and include the "this" qualifier.

[pjcozzi]

@kristiancalhoun and @shunter how hard do you guys think this? A good chunk of our generated doc is missing. Maybe we should bug some of this with jsdoc-toolkit? Fix it ourselves? Workaround it in comments?

[kristiancalhoun]

All of the undocumented GLSL types are from .glsl files (as compared to those found in ShaderProgram.js that are documented). I think the way the original GLSL comments are broken up into strings across multiple lines when the .glsl files are converted to .js files during the build process is preventing them from being documented. Thoughts, @shunter?

[mramato]

Not that we need to address this as the same time as everything else, but a minor doc issue (in my opinion) is the fact that their is a single "flat" table of contents, it would be nice if code where split up my directory or some other sort of tree.

[kristiancalhoun]

I think I've finally worked out most of our issues and will be committing the rest of my changes shortly. However, my current fix for documenting stand-alone functions uses the @function tag, which has some unintended side-effects. What new tag name would you all prefer for documenting these types of functions? @standaloneFunc?

[pjcozzi]

This is a temporary Cesium workaround, right? If so, how about @cesiumFunction?

Or are you going to pull request this back into jsdoc-toolkit?

[mramato]

What does @function currently do? It seems like that's the best name,
why isn't it? I guess I would prefer something like @GlobalFunction
(even though it's not really global).

On Mon, Jun 25, 2012 at 3:27 PM, Kristian Calhoun
reply@reply.github.com
wrote:

I think I've finally worked out most of our issues and will be committing the rest of my changes shortly. However, my current fix for documenting stand-alone functions uses the @function tag, which has some unintended side-effects. What new tag name would you all prefer for documenting these types of functions? @standaloneFunc?

---

Reply to this email directly or view it on GitHub:
#11 (comment)

[kristiancalhoun]

I was trying to keep the name generic in case we do eventually pull request our changes back in, but at this point our JsDoc fork is very Cesium specific in terms of how we separate JavaScript from GLSL, generate a list of types for SandCastle, etc. Maybe at some point I'll put all our changes into a new template so that our pull request can only contain general core changes.

Functions tagged with @function are currently pooled into one conglomerate global.html file that we choose not to publish (and if we did, not all the necessary tagged info is displayed). It's also used somewhere behind the scenes to classify methods and resolve @see links (which is the error I was running into).

I also thought of @libraryFunction, but I'll go with @GlobalFunction for now and change it if there are any objections.

[mramato]

I think I actually like @libraryFunction better, good idea.

On Mon, Jun 25, 2012 at 4:32 PM, Kristian Calhoun
reply@reply.github.com
wrote:

I was trying to keep the name generic in case we do eventually pull request our changes back in, but at this point our JsDoc fork is very Cesium specific in terms of how we separate JavaScript from GLSL, generate a list of types for SandCastle, etc. Maybe at some point I'll put all our changes into a new template so that our pull request can only contain general core changes.

Functions tagged with @function are currently pooled into one conglomerate global.html file that we choose not to publish (and if we did, not all the necessary tagged info is displayed). It's also used somewhere behind the scenes to classify methods and resolve @see links (which is the error I was running into).

I also thought of @libraryFunction, but I'll go with @GlobalFunction for now and change it if there are any objections.

---

Reply to this email directly or view it on GitHub:
#11 (comment)

[pjcozzi]

Maybe at some point I'll put all our changes into a new template so that our pull request can only contain general core changes.

Yes, very good idea.

Also, I'm OK with @libraryFunction too.

[kristiancalhoun]

I just opened up pull request #80.

[mramato]

The new stuff looks great, there are two more doc issues however and @kristiancalhoun is already looking into them.

1. We specify the return type in most places, but the return type does not generate a link as we expect.
2. Static objects are not linked to properly, for example enumerations such as LabelStyle used in Label.setStyle documentation.