-
Notifications
You must be signed in to change notification settings - Fork 1.4k
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
JSDoc should do more to interpret IIFEs #456
Comments
CoffeeScript, and most other compile-to-JS languages, can slice and dice your code in a variety of ways. Inevitably, some of that slicing and dicing will defeat JSDoc's static-analysis tools. That said, if JSDoc did a better job of interpreting immediately invoked function expressions, such as the Removing the |
That makes sense. Thanks! |
Is there currently any way to effectively document apps with JSDoc that use IIFE's to encapsulate code? |
Yes, you can document code that uses IIFEs--it just requires a bit more markup. Our documentation website has some examples for documenting AMD modules that should help you get started. We could use some non-module examples in the docs as well; I filed jsdoc/jsdoc.github.io#41 to address that at some point. |
Another common use case, from #442: Before resolving this issue, we may need to tackle the more general issue that JSDoc doesn't recognize when two symbols are effectively sharing a pointer. For example, if you're documenting namespace |
I created a hackaround using part of the JSDoc plugin framework to filter out IIFE's before JSDoc sees the code, see jsdoc-plugin-strip-outer-iife. You can see the source code is pretty straight-forward. I believe it handles all the cases mentioned in this thread. But most importantly it handles my cases perfectly. :) This isn't the right solution for this problem, but since it works for me I thought I'd share. |
Another common use case that I allude to in a previous comment: Adding properties to |
I was going to create a separate issue but since my problem is related to IIFEs and this issue is titled "do more to interpret IIFEs" I guess my comment fits here. I'm using an IIFE in a CommonJS module to be able assign the public interface to either "module.exports" or the "window" object, so that a node.js module can be included in a
This works as expected because the exports object is passed into the IIFE. This example doesn't work, however. It looks like the exports object passed into the IIFE will only be recognized by JSDoc if it's actually named "exports". JSDoc doesn't document the public interface if it's attached to the object passed into the IIFE and that object is NOT named "exports", even the the "ex" argument is just the module.exports object being passed in. I'll show that in this example, which doesn't work
This example does work though, when the exports object isn't passed into the IIFE at all
|
@ejfrancis This example in the docs shows how to document your second example. |
@hegemonic I've tried that and can't get it to work. Those docs are for AMD and I'm using it within CommonJs. I couldn't tell if using the A with
B with
C with no
|
C with no |
@hegemonic the docs aren't even generated for the CommonJS module at all with C. without the |
It is not required by node.js, but introduce troubles while generating documents with jsdoc3. Refer to jsdoc/jsdoc#456 Change-Id: I6664f1be0fc3e86f3a7e3843d557786c37df1c5e
JSDoc does not detect functions created by compiling CoffeeScript functions with proper JSDoc comments. Here is a simple example:
x = 1
or some other code had to be before the comment, otherwise CoffeeScript assigns the comment to the file outer anonymous function and not the inner function.After compilation CoffeeScript generates the following JavaScript code:
On this code, JSDoc does not detect the
a
function.If the
var a, x;
line is removed, JSDoc works fine.The text was updated successfully, but these errors were encountered: