如何使用 ngdoc 以角度记录工厂函数创建的对象？答案

【问题标题】：How to document the objects created by a factory function using ngdoc in angular?如何使用 ngdoc 以角度记录工厂函数创建的对象？
【发布时间】：2016-08-12 12:09:39
【问题描述】：

如何使用 ngdoc 记录返回“工厂函数”的“角度工厂”？具体来说，我如何记录我的“工厂函数”创建的对象？

在下面的人为示例中，我已经记录了如何使用工厂来创建页面对象，但是如何记录如何使用页面对象本身呢？

angular.module('fooRestClient').factory('page', function () {

   var prototype = {};

  // Below I need to somehow link the methods a page object has to the
  // factory's documentation.

  /**
   * @description Fetches the page at the specified index.
   *
   * @param {number} index - the index of the page to fetch
   *
   * @returns {object} a page object representing the page at the given index
   */
   prototype.getPage = function (index) {
      // returns a new page.
   };

   // ... more useful methods.

   /**
    * @ngdoc service
    * @type function
    * @name fooRestClient:page
    * @description
    * A factory function for producing page objects....  
    *
    * @param {Number} index - The page index.
    * @param {Number} size - The page size.
    * @param {Number} total - The total number of pages.
    * @param {Array}  data - The contents of the page.
    * @returns {object} A page object for the given resource
    */
    return function page(index, size, total, data) {
        return Object.create(prototype, {
            index: index,
            size: size,
            total: total,
            data: data
        });
    };

});

我可以在 SO 上找到的最接近的匹配项是：How to document a factory that returns a class in angular with ngdoc?。这无济于事，因为我没有“类”名称来将方法链接回，因为我没有使用伪经典继承。

【问题讨论】：

标签： javascript angularjs factory ngdoc

【解决方案1】：

也许这会如你所愿：

    /**
     * @ngdoc service
     * @type function
     * @name fooRestClient:page
     * @description
     * A factory function for producing page objects....
     *
     * @param {Number} index - The page index.
     * @param {Number} size - The page size.
     * @param {Number} total - The total number of pages.
     * @param {Array}  data - The contents of the page.
     * @returns {object} A {@link prototypeInstance|page object} for the given resource
     */

    return function page(index, size, total, data) {
      /**
       * @ngdoc object
       * @name prototypeInstance
       * @description page object for the given resource
       */
      return Object.create(prototype, {
        /*
         * @ngdoc object
         * @name prototypeInstance#index
         * @description index description
         */
        index: index,
        /*
         * @ngdoc object
         * @name prototypeInstance#size
         * @description size description
         */
        size: size,
        /*
         * @ngdoc object
         * @name prototypeInstance#total
         * @description total description
         */
        total: total,
        /*
         * @ngdoc object
         * @name prototypeInstance#data
         * @description data description
         */
        data: data
      });
    };

我知道它有点冗长，但这是我发现做这类事情的唯一方法

【讨论】：