Proposed changes to Closure Compiler Side-effect annotations for Extern definitions

John Lenz  - Sept 21, 2010

Current

Currently, the Closure Compiler currently supports a single annotation “@nosideeffects” which can be used on function declarations to indicate that it does not make any changes to external state.

Proposed

There are five classes function behavior that to which are of interest for classifying function side-effects:

- no modifications are made to either any state of interest

- modifications to a functions “this” object

- modifications to one or more of a functions parameters

- modifications to global state

- is the function result a possible reference to global state

To allow these different scopes of changes to be categorized, new annotations are needed.  The annotations will continue to be used only for extern file defintions.   For each of these states, the proposed changes are:

• “modifications to global state” will continue to be to be the default^[a] and will require no annotation.
• “no modifications are made to either any state of interest” will continue to be represented by the “@nosideeffects” annotation.
• “modifications to a functions “this” object” will be represents “@modifies {this}^[b]”.
• “modifications to one or more of a functions parameters” will be represented by “@modifies{[arguments|param[,param]]}” where “arguments” is used to indicate all parameters or a comma separated list of named parameters.
• “is the function result a possible reference to global state”  will be represents by the “@safeReturn”^[c] annotation.

If both “this” and function arguments are modified only a single @modifies annotation is used and combined into a single comma separated list.

Implementation plan

• Agree on annotations names.
• Modify the compiler to accept the new annotations.
• Modify the side-effect calculations to use include “@modifies{this}”, other “@modifies” values will be treated as global side-effects.
• Modify the side-effect calculations to track function local objects that call “@modifies{this}” functions.
• Update core es3.js extern files to include the “@modifies{this}” annotation (it may be convenient to include the other new annotations as well).
• Modify the side-effect calculations to propagate “safe return” results.
• Update core es3.js extern files to include the “@safeReturn” annotation.
• Modify the side-effect calculations to track other function parameter values.^[d]
• Profit!