Mention ^js annotation in Externs Guide

[pesterhazy]

The externs guide mentions type annotations like ^js/Foo.Bar.

Although it doesn't mention it, it's also possible to simply use ^js. (In fact anything like ^js/asdf will work, too.)

Should ^js be the default recommendation? Oftentimes you don't know the correct type of JS objects you're getting back from an NPM lib. Even if you do, using a generic annotation seems to have the same effect, so not sure there are any downsides to simply using ^js everywhere.

[swannodette]

@pesterhazy that's a good suggestion

[mrrodriguez]

I'll note that in recent versions of CLJS using ^js does seem to generate necessary externs via externs inference, however, it also omits a warning about needing to add extern to Object due to it being "ambiguous".
See https://github.com/clojure/clojurescript/blob/v1.10/src/main/clojure/cljs/analyzer.cljc#L480 for where I believe this originates.

It is just a warning, but it can be a little annoying to deal with if using *warn-on-infer* and something like auto-reloading in figwheel where it defaults to not reloading when namespaces have warnings.
Of course you can choose to just not use *warn-on-infer*, but the downside there is that you then don't get the other warnings that may be useful. There is just a lack of granularity on the ^js case.

Also, maybe this isn't the correct place to bring this up?

[mfikes]

@mrrodriguez Right, perhaps a JIRA for what you are describing.