8

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.

Yuval Karmi
  • 26,277
  • 39
  • 124
  • 175
  • any ideas on how to create a file (.pdf or .doc) with all documentation details rather than a web app? – spyder Aug 10 '16 at 15:10

3 Answers3

11

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;
});
SGD
  • 1,676
  • 14
  • 18
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

allenhwkim
  • 27,270
  • 18
  • 89
  • 122
  • This doesn't answer my question on the specifics of documentation. I'm already using `ngdocs` (note the `s` in the end) to generate the documentation. – Yuval Karmi Apr 13 '15 at 13:00
  • @yuval yes, it does not answer your question. I wish you find what you want from ngdoc, which I could not. – allenhwkim Apr 13 '15 at 17:53
1

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;

  });
Yaacov
  • 185
  • 4