typedefs and externs

[tschaub]

The current solution for typedefs that are used as externs in library builds is to have something like the following in src/objectliterals.jsdoc:

/**
 * @typedef {Object} olx.AttributionOptions
 * @property {string} html HTML markup for this attribution.
 * @property {Object.<string, Array.<ol.TileRange>>|undefined} tileRanges
 *     Tile ranges (FOR INTERNAL USE ONLY).
 * @todo stability experimental
 */

This is used to document the olx.AttributionOptions members and to generate externs. The generated externs currently look like this (excerpted from build/src/external/externs/types.js):

/**
 * @typedef {{html: string,
 *            tileRanges: (Object.<string, Array.<ol.TileRange>>|undefined)}}
 */
olx.AttributionOptions;



/**
 * @interface
 */
olx.AttributionOptionsExtern = function() {};


/**
 * @type {string}
 */
olx.AttributionOptionsExtern.prototype.html;


/**
 * @type {Object.<string, Array.<ol.TileRange>>|undefined}
 */
olx.AttributionOptionsExtern.prototype.tileRanges;

That is, the expanded @typedef is generated based on @property annotations in src/objectliterals.jsdoc and then an @interface is created with prototype properties from the typedef. Combined, these give us more advanced renaming with the --use_types_for_optimization compiler option (or DisambiguateProperties and AmbiguateProperties through the Java API).

I mentioned earlier today that I tried a simpler structure for our src/external/externs/types.js file (basically, no interfaces) and saw a difference in the compiled output (it was 20 bytes larger). It turns out that this was due to us having a externs for code that was not used by the library (see #1734) - as a result, the handle method of the goog.fx.Dragger was not renamed.

After removing those unused types, the compilation output is exactly the same with somewhat simpler externs. For example, the attribution options above would become this (extracted from src/external/externs/types.js):

/**
 * @typedef {{html: string,
 *            tileRanges: (Object.<string, Array.<ol.TileRange>>|undefined)}}
 */
olx.AttributionOptions;


/**
 * @type {string}
 */
olx.AttributionOptions.html;


/**
 * @type {Object.<string, Array.<ol.TileRange>>|undefined}
 */
olx.AttributionOptions.tileRanges;

To me, this is starting to look like something that could/should live in our source .js. Since we can't add descriptive documentation to @typedef properties, we need separate space for those. These files would serve as typedefs, documentation, and would be used as externs.

If we create files like src/ol/attributioncontrol.externs.js with the above comments, we would have both the typedefs and the documentation closer to the code (and we would be generating less code based on non .jsdoc files for the build).

For applications built together with the library, the *.externs.js files would be compiled together with the source. For stand alone library builds, the *.externs.js files would be used as externs (and not as sources) - with no modification needed.

The drawback of these *.externs.js files is that they do require that we duplicate the type information (once in the @typedef annotation and again in the @type - where the properties will also be documented). This is more verbose than our objectliterals.jsdoc solution, but it is acceptable to me.

I'm describing all this here because it is part of a larger effort to drive the compiler (not Plovr) with one or more simple build tools (likely one for Node and one for Python). I'd like to minimize the amount of code these tools have to generate.

[elemoine]

This sounds good to me @tschaub. The duplication sounds manageable to me. As you said the individual option needs documentation anyway.

[tschaub]

See #1954 for work on this.

[tschaub]

Closed with 98ec656.