What does the @private annotation actually do in Google Closure JavaScript code?

annotations, google-closure, google-closure-compiler, google-closure-library, javascript

Solution

The access control annotations `@private`, `@protected`, and `@public` are directives for the Closure Compiler that help developers enforce the desired level of visibility for properties and functions.

To emit warnings for access violations use the Compiler flag:

- --jscomp_warning=visibility

To emit errors for access violations use the Compiler flag:

- --jscomp_error=visibility

Access control annotations are enforced on a per file basis, meaning that any properties annotated `@private` or `@protected` may be accessed anywhere within the same file. Also note that the compiler removes these annotations from the compiled code since they are not part of the JavaScript language.

Example

file1.js

goog.provide('ns1');

/**
 * Global private variable.
 * @private
 */
ns1.global = 'foo';
alert('ns1.global = ' + ns1.global); // OK in same file.


/** @constructor */
ns1.Constructor = function() {
  /** @private */
  this.secret_ = ns1.global;
};

ns1.instance = new ns1.Constructor();
alert(ns1.instance.secret_); // No warning in same file.

file2.js

goog.provide('ns2');

goog.require('ns1');

alert('ns1.global = ' + ns1.global); // Not allowed.

ns2.instance2 = new ns1.Constructor();
alert(ns2.instance2.secret_); // Not allowed.

With the flag `--jscomp_error=visibility` set, Closure Compiler emits the following errors.

ERROR - Access to private property global of ns1 not allowed here.
alert('ns1.global = ' + ns1.global);
                        ^
ERROR - Access to private property secret_ of ns1.Constructor not allowed here.
alert(ns2.instance2.secret_);
      ^

See Visibility (private and protected fields) in the Google JavaScript Style Guide.

Problem

When I put a comment above my variable or function with `@private` in it what is it actually doing? I have looked at the documentation but I'm still not sure. ``` goog.provide('myproject'); /** @private */ myproject.foo = "bar"; ``` I can still access it when I open up chrome's development tools (myproject.foo). And... ``` goog.require('myproject'); window.addEventListener('load', function() { //this works. document.body.textContent = myproject.foo; }); ``` The above code still set's the bodies textContent to equal "bar", even when compiled. So what does `@private` actually do?

Original source