docs($http): Interceptors, example unclear / conflicts with description

[fwielstra]

I was reviewing some of our application code and came across a branch not covered by unit tests in a Request interceptor:

return {
  request: function requestIntercepor(config) {
    _.extend(config.headers, {
      'X-Requested-By': 'my-app'
    });
    return config || $q.when(config);
  }
};

This failed when config was undefined, so I dove into the docs to see if config is ever undefined: https://docs.angularjs.org/api/ng/service/$http#interceptors. The docs in this case state:

"request: interceptors get called with http config object. The function is free to modify the config or create a new one. The function needs to return the config directly or as a promise."

and the example:

'request': function(config) {
    // do something on success
    return config || $q.when(config);
  },

Now, one or the other of these are incomplete or incorrect: either the example is a literal translation of the documentation (return config or a promise, but don't use this actual code), or the documentation is incomplete and needs a sentence stating that if config is a falsy value, the method should return this value wrapped in a resolving promise (or something to that effect).

Does anyone have more inside knowledge about $http and how the request interceptor can be called to tweak this bit of documentation? I just want to know if I need to add a test case (and update the implementation to deal with falsy values) or if I can remove the or. Haven't run into a 'config is undefined' error so far myself, so I'm leaning towards a code / example fix.

[Narretz]

In the request interceptor, the config as an argument can never be undefined, it is always a config object (Since you must pass an object to $http with at least the url defined). Likewise, the return value must always be a config object, but you have the choice to either return it directly or return a promise that resolves to a config object. I guess the documentation should be be updated to make this more clear (the comment is also irrelevant, I think).