openlayers/ol3 — pull request #2765 by elemoine (2014-09-29 14:23:56+00:00)
Title: Treat unknown opt types as Object in ol externs

As discussed previously we want to export base classes. This is to be able to do, for example, `source instanceof ol.style.Image` in applications. Exporting base classes means marking them with the `@api` annotation.

The problem is that, currently, if we just add the `@api` annotation to the base class we get an unknown type for that class' options type in the ol externs file:

```js
/**
* @constructor
* @param {ol.style.ImageOptions} options
*/
ol.style.Image = function(options) {};
```

where `ol.style.ImageOptions` is not declared in the ol externs file.

One option involves adding `@api` to the options `@typedef` as well. This indeed fixes the problem in the ol externs file. But this creates a broken link in the API doc. In any way, it does not make sense to add `@api` to the options `@typedef`, because abstract base classes are not meant to be instantiated by applications.

This PR fixes the problem by making the `generate-externs.js` script use `@typedef {Object}` in the generated externs file for options types that are referenced in "exported" constructors but not marked with an `@api` annotation.

I have to admit that the code added to `generate-externs.js` is not of the prettiest, but I haven't been able to come up with a prettier solution.

Thanks for any review.