Question

I am trying to properly annotate all my Javascript code and am still a beginner in this field.

I get objects from a server call that are directly in json. Those objects are passed to functions and I call members directly. It obviously is very error prone while obfuscating so I am trying to annotate everything properly.

My understanding is that (i) I should create a class for this object even though it is never created directly with new and (ii) I should be careful with member names since they are fixed by the server response and should not be changed (or should be aliased beforehand).

I have two questions: are my asumptions correct ? how to do the annotation based on that.

Here is a sample code to illustrate

$.get("url.php", function(data) {
    process(data);}, "json"); // <= returns {"a":"abc","b":1}

function process(data) {
  $("#someElement").html(data.a + data.b);
}

Here is the class I was planning on creating for closure compilation purposes

/**
 * The object that is sent back from the server
 * @constructor
 */
function ServerResponse() {
  /** @type {string} a */
  this["a"] = "";
  /** @type {number} b */
  this["b"] = 0;
}

Here is the annotation for my process function

/**
 * Process data from the server
 * @param {ServerResponse} data: the Object sent back from the server
 */

Is my annotation correct? Is it robust to obfuscation?

Thanks a lot for your help

Answer 1

If you quote property names, you need to quote them consistently at every usage. If you haven’t see this, you should read:

https://developers.google.com/closure/compiler/docs/api-tutorial3

So that your first snippet would be:

function process(data) {
  $("#someElement").html(data['a'] + data['b']);
}

If you are trying to avoid quoting or if you would like the compiler to type check the usage of the properties (quoted properties references are not checked), you should define an extern file to include with the compilation of your source:

/** 
 * @fileoverview
 * @externs
 */

/** @interface */
function ServerResponse() {}
/** @type {string} */
ServerResponse.prototype.a;
/** @type {number} */
ServerResponse.prototype.b;