AngularJs ngdocs: annotate that a method returns a promise

Question

I'm currently in the process of documenting my first real AngularJs application, for which I use ngdocs syntax with grunt-ngdocs

I was wondering if there is a better way to annotate that my service method returns a promise (so you know that you should add .then () instead of accessing the returned object.

* @returns {object} returns a promise 

Full service context:

 /** * @ngdoc service * @name appServices.Authentication * @requires $http * @description * Service used to authenticate request to an api. It injects a session parameter into each request if the token parameter is set. * (as a request param for a GET and as an extra body param for a POST) **/ module.factory('Authentication', ['$http', function ($http) { var token; /** * @ngdoc method * @name appServices.Authentication#login * @methodOf ng.service * @returns {object} returns a promise */ function login(email, password) { return $http.post('/auth/login', {email: email, password: password}) .then(function (response) { if (response.data.token) { token = response.data.token; } }); } function getToken() { return token; } return { login: login, token: getToken, }; }]); 

Answer 1

You can simply write:

 * @returns {Promise} returns a promise