Remove deprecated @expose annotations.

Added externs for error.js and removed the @expose declarations from the
actual error.js file. Updated the jscompiler flags and docs.

Change-Id: I2aa95ef1c82fc7bd349c637cca3141d5a003b646

CONTRIBUTORS

@@ -61,6 +61,7 @@ Sandra Lokshina <ismena@google.com>
 Seth Madison <seth@philo.com>
 Theodore Abshire <theodab@google.com>
 Thomas Stephens <thomas@ustudio.com>
+Tim Plummer <objelisks@google.com>
 Timothy Drews <tdrews@google.com>
 Tomas Bucher <collapsingtesseract@gmail.com>
 Torbjörn Einarsson <torbjorn.einarsson@edgeware.tv>

build/build.py

@@ -53,12 +53,6 @@ common_closure_opts = [
 
     '--jscomp_error=*',
 
-    # 'deprecatedAnnotations' controls complains about @expose, but the new
-    # @nocollapse annotation does not do the same job for properties.
-    # So since we can't use the new annotations, we have to ignore complaints
-    # about the old one.
-    '--jscomp_off=deprecatedAnnotations',
-
     # Analyzer checks require explicit nullability, which is a pain.
     '--jscomp_off=analyzerChecksInternal',
 

docs/design/export.md

@@ -15,19 +15,6 @@ The compiler has a special annotation for this: `@export`.  Anything annotated
 with `@export` will be exported by the compiler automatically.
 
 
-## Exposing a symbol
-
-Similar to exporting, the compiler also supports what it calls exposing.  This
-is similar, but rather than exporting a symbol to an exported namespace,
-exposing prevents a symbol from being renamed during compilation.  The compiler
-uses the `@expose` annotation for this purpose.
-
-This is useful for things that cannot be exported, such as public member
-variables.  In contrast, exporting can only be applied to static or prototype
-methods, since they do not differ per instance and can be attached to the
-exported namespace at load time.
-
-
 ## Exporting to the docs
 
 We generate our documentation from the same annotations that we feed to the
@@ -67,10 +54,17 @@ compiler because they are not part of the library's public API.  For example,
 To make this work, we created another new annotation: `@exportInterface`.  This
 annotation is used by the extern generator, but is ignored by the compiler.
 
+In some cases, public member variables need to be preserved when they would
+otherwise be renamed by the compiler. `@export` is not sufficient to keep the
+names from being renamed and is only useful for static members or prototype
+values. `@expose` used to be used for this but is now deprecated. The current
+best practice is to write an externs file defining the properties that should
+be preserved.
+
 
 ## Summary
 
  - `@export`: truly exported (attached to namespace) by the compiler
- - `@expose`: truly exposed (not renamed) by the compiler
+ - `@expose`: deprecated
  - `@exportDoc`: considered part of the exports in the docs
  - `@exportInterface`: considered part of the exports in generated externs

externs/shaka/error.js

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2016 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+/** @externs */
+
+
+
+/**
+ * @interface
+ * @exportDoc
+ */
+shakaExtern.Error = function() {};
+
+
+/**
+ * @type {shaka.util.Error.Severity}
+ */
+shakaExtern.Error.prototype.severity;
+
+
+/**
+ * @const {shaka.util.Error.Category}
+ */
+shakaExtern.Error.prototype.category;
+
+
+/**
+ * @const {shaka.util.Error.Code}
+ */
+shakaExtern.Error.prototype.code;
+
+
+/**
+ * @const {!Array.<*>}
+ */
+shakaExtern.Error.prototype.data;
+
+
+/**
+ * @type {boolean}
+ */
+shakaExtern.Error.prototype.handled;
+

lib/util/error.js

@@ -31,12 +31,18 @@ goog.provide('shaka.util.Error');
  * @struct
  * @export
  * @extends {Error}
+ * @implements {shakaExtern.Error}
  */
 shaka.util.Error = function(severity, category, code, var_args) {
+  /** @override @exportInterface */
   this.severity = severity;
+  /** @override @exportInterface */
   this.category = category;
+  /** @override @exportInterface */
   this.code = code;
+  /** @override @exportInterface */
   this.data = Array.prototype.slice.call(arguments, 3);
+  /** @override @exportInterface */
   this.handled = false;
 
   // This improves formatting of Errors in failure messages in the tests.
@@ -78,41 +84,6 @@ shaka.util.Error = function(severity, category, code, var_args) {
 };
 
 
-/**
- * @type {shaka.util.Error.Severity}
- * @expose
- */
-shaka.util.Error.prototype.severity;
-
-
-/**
- * @const {shaka.util.Error.Category}
- * @expose
- */
-shaka.util.Error.prototype.category;
-
-
-/**
- * @const {shaka.util.Error.Code}
- * @expose
- */
-shaka.util.Error.prototype.code;
-
-
-/**
- * @const {!Array.<*>}
- * @expose
- */
-shaka.util.Error.prototype.data;
-
-
-/**
- * @type {boolean}
- * @expose
- */
-shaka.util.Error.prototype.handled;
-
-
 /**
  * @return {string}
  * @override