How to document a factory that returns a class in angular with ngdoc?

Question

Given an angular app with a factory that returns a class, as such:

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

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

    return User;
});

Using ngdoc (the special flavor of jsdoc angular uses), how do I document the initializer without defining it as a method?

Right now, this is what I've tried:

/**
 * @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;
});

But this results in the User initializer (the User function that accepts the parameter name) being treated like a method with the name Initializer, which is confusing to people trying to use this code.

I've tried adding the @constructor flag, but this has no effect of the html dgeni ends up generating.

Thank you.

---

UPDATE: Removed references to dgeni. I was under the impression that the plugin I was using (grunt-ngdocs) uses dgeni behind the scenes, but this is not the case.

Answer 1

This is how I would do it not having any experience with Angular in particular:

/**
 * @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;
});

Answer 2

This is opinionated answer.
I had trouble with Angular documentation, and I even wrote a blog about it, Sigh, AngularJS Documentation

My conclusion was to build a new one. Angular-jsdoc is the outcome.

Here is excerpts from github.

Angular-JSDoc

JSDoc 3 Template for AngularJS.
A JSDoc plugin and template for AngularJS, nothing else!

Features

• Right side TOC, table of contents, for navigation by Directives, Services, Controllers, etc
• Read and process @ngdoc tag

How Does It Look Like

• angularjs-google-maps Documentation

Answer 3

I created a fork/pull request to add @constructor support to gulp-ngdocs as available in grunt-ngdocs: https://github.com/nikhilmodak/gulp-ngdocs/pull/91. All this does is change the basic usage section to include the new keyword.

Then use in a fashion similar to, but slightly different from, @SGD's answer. Make sure that @ngdoc directive on the service specifies function.

Example:

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

  });