【问题标题】：How to document a factory that returns a class in angular with ngdoc?如何用ngdoc记录一个以角度返回类的工厂？
【发布时间】：2015-06-09 12:42:12
【问题描述】：

给定一个带有返回类的工厂的 Angular 应用，如下所示：

angular.module('fooApp').factory('User', function(){
    function User(name){
        this.name = name;
    }

    User.prototype.greet = function(){
        return "Howdy, " + this.name;
    }

    return User;
});

使用ngdoc（jsdoc angular 使用的特殊风格），我如何记录初始化程序而不将其定义为方法？

现在，这是我尝试过的：

/**
 * @ngdoc service
 * @name fooApp.User
 * @description User factory.
 */

angular.module('fooApp').factory('User', function(){

    /**
     * @ngdoc method
     * @methodOf fooApp.User
     * @name Initializer
     * @description Initializes a new User object with a name
     */
    function User(name){
        this.name = name;
    }

    User.prototype.greet = function(){
        return "Howdy, " + this.name;
    }

    return User;
});

但这会导致 User 初始化程序（接受参数 name 的 User 函数）被视为名称为 Initializer 的方法，这会使尝试使用此代码的人感到困惑。

我尝试添加 @constructor 标志，但这对 html ~~dgeni 最终生成~~没有影响。

谢谢。

更新：删除了对dgeni 的引用。我的印象是我使用的插件（grunt-ngdocs）在幕后使用了dgeni，但事实并非如此。

【问题讨论】：

关于如何创建包含所有文档详细信息的文件（.pdf 或 .doc）而不是 Web 应用程序的任何想法？

标签： javascript angularjs documentation jsdoc ngdoc

【解决方案1】：

如果没有任何 Angular 经验，我会这样做：

/**
 * @ngdoc service
 * @name fooApp.User
 * @description User factory.
 */

angular.module('fooApp').factory('User', function(){

    /**
     * @ngdoc method
     * @constructs fooApp.User
     * @description Initializes a new User object with a name
     */
    function User(name){
        this.name = name;
    }

    User.prototype.greet = function(){
        return "Howdy, " + this.name;
    }

    return User;
});

【讨论】：

【解决方案2】：

这是自以为是的答案。
我在使用 Angular 文档时遇到了麻烦，我什至写了一篇关于它的博客，Sigh, AngularJS Documentation

我的结论是建立一个新的。 Angular-jsdoc 是结果。

这里是来自 github 的摘录。

Angular-JSDoc

AngularJS 的 JSDoc 3 模板。
AngularJS 的 JSDoc 插件和模板，仅此而已！

特点

右侧目录、目录，用于按指令、服务、控制器等进行导航
读取和处理@ngdoc标签

怎么样

angularjs-google-maps Documentation

【讨论】：

这并不能回答我关于文档细节的问题。我已经在使用ngdocs（注意最后的s）来生成文档。
@yuval 是的，它没有回答你的问题。我希望你能从 ngdoc 中找到你想要的东西，而我却找不到。

【解决方案3】：

我创建了一个 fork/pull 请求以将 @constructor 支持添加到 gulp-ngdocs，如 grunt-ngdocs 中所示：https://github.com/nikhilmodak/gulp-ngdocs/pull/91。所做的只是更改基本用法部分以包含新关键字。

然后以与@SGD 的答案类似但略有不同的方式使用。确保服务上的 @ngdoc 指令指定功能。

例子：

/**
 * @ngdoc function
 * @name yourModule.yourService
 * @description
 *
 * Your short description
 *
 * @constructor
 * @param {string} yourConstructorParameter A string paramter
 * @returns {Object} An object instance of type YourClassName
 * 
 */       

angular
  .module('yourModule', [])
  .factory('YourClassName', function() {

    /**
     * @ngdoc object
     * @name yourModule.type:YourClassname
     * @description
     *
     * Short description.
     * 
     */

    function YourClassName(yourConstructorParameter) {
      this.yourConstructorParameter = yourConstructorParameter;
      this.yourMethod = function() {};
    }


  /**
   * @ngdoc function
   * @name yourModule.type:YourClassName#yourPrototypeMethod
   * @methodOf yourModule.type:YourClassName
   * @description
   *
   * Short Description.
   *    
   * @returns {Object} The object passed on instantiation.
   */

    YourClassName.prototype.yourPrototypeMethod = function() {
      return this.yourConstructorParameter;
    };

    return YourClassName;

  });

【讨论】：