Better function scanning.

[aomarks]

Analyzer doesn't currently find functions that are declared by assignment, which is a common pattern in Polymer core.

For example, we find Polymer.Async.timeOut.after, but not Polymer.Async.timeOut.run. The former is declared with a normal function declaration, while the latter is with an assignment with a bind call.

This is why the Polymer API docs are incomplete for some namespaces. For example, https://www.polymer-project.org/2.0/docs/api/namespaces/Polymer.Async.timeOut is missing run and cancel. Similar story for https://www.polymer-project.org/2.0/docs/api/namespaces/Polymer.Async.animationFrame and others.

I think what's going on is that Analyzer just looks for function declarations, so because the actual expression doesn't look like a function, it's not scanned at all. Scope analysis could solve this in a more principled way, but the simpler fix is to either pick up on the @return and @param annotations and assume that a function has been defined regardless of the actual expression syntax, or to require that such cases are annotated explicitly with something like @type {Function}.

As part of this, I think we should try to unify the function and method scanning logic, which obviously has a large overlap. A few features (e.g. rest parameters, optional parameters) are currently only supported for methods, so we'd also get those extended to functions by doing this refactoring.

[rictic]

I think finding @return is enough. @param is tricky because events are also annotated with @param

[rictic]

Note: mixins may also be annotated with @return

[aomarks]

Note to self:

Methods are implemented here: https://github.com/Polymer/polymer-analyzer/blob/master/src/javascript/esutil.ts

Functions are implemented here: https://github.com/Polymer/polymer-analyzer/blob/master/src/javascript/function-scanner.ts

[aomarks]

Ah ok, good call. @justinfagnani was advocating for an explicit @type annotation anyway, so I guess we should do that then so it's totally unambiguous. Assuming adding a @type to a function is not a confusing thing for e.g. Closure...

[aomarks]

How about @function http://usejsdoc.org/tags-function.html?

[aomarks]

After starting to implement this, I found that we actually already support @function for exactly this use case (https://github.com/Polymer/polymer-analyzer/blob/master/src/javascript/function-scanner.ts#L97).

[justinfagnani]

That's functions inside object literals though, do we have it for top-level statements too?

edit: sorry, I mixed this up with another issue related to @function :)

[aomarks]

You're right that we don't support it for top-levels, though.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.