AngularJs ngdocs: аннотировать, что метод возвращает обещание

Question

Я сейчас нахожусь в процессе документирования моего первого настоящего приложения AngularJs, для которого я использую синтаксис ngdocs с grunt-ngdocs

Мне было интересно, если есть лучший способ аннотировать, что мой метод службы возвращает обещание (так что вы знаете, что вы должны добавить.then() вместо доступа к возвращаемому объекту.

   * @returns {object} returns a promise

Полный контекст услуги:

/**
 * @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

Вы можете просто написать:

* @returns {Promise} returns a promise