How can ngdoc be used to document a function declaration in an angular service?

Question

I would like to add ngdoc documentation to a function declaration within an angular service. How can I do this for myFunction in the example below?

I reckon I need something like @closure, @functionOf or @functionIn.

Please note that (in contrast to myMethod) myFunction is not a method.

/**
 * @ngdoc service
 * @name myApp.service:myService
 * @description
 *   My application.
 */
angular
  .module('myApp')
  .factory('myService', function() {
    'use strict';

    var x = 0;

    /**
     * @ngdoc function
     * @name ?
     * @description
     *   How can this be identified as being within the closure of 
     *   myService, and not be described as a constructor?
     */
    function myFunction (z) {
      x++;
      x += z;
    }

    return {
      /**
       * @ngdoc method
       * @name myMethod
       * @methodOf myApp.service:myService
       * @description
       *   A method of myService.
       */
      myMethod : function (x) {
        myFunction(x);
      }
    };
  })

I found documentation for ngdocs here: https://github.com/idanush/ngdocs/wiki/API-Docs-Syntax — paulhhowells, May 16 '16 at 11:51
and here: https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation — paulhhowells, May 16 '16 at 11:52

score 6 · Answer 1 · answered Oct 08 '15 at 18:05

The keyname you are looking for is the @methodOf annotation. When i'm writing documentation using grunt-ngdocs for a service it ends up looking like the following:

/**
  * @ngdoc overview
  * @name module
  * @description A small module containing stuff
  */
angular
  .module(module, [])
  .factory('name', factory);

/**
  * @ngdoc object
  * @name module.name
  * @description Its a pretty bad factory
  */
function factory() {
  return {
    doSomething: doSomething
  };

  /**
    * @ngdoc function
    * @name module.name#doSomething
    * @methodOf module.name
    * @description Does the thing
    * @param {string=} [foo='bar'] This is a parameter that does nothing, it is
                                   optional and defaults to 'bar'
    * @returns {undefined} It doesn't return
    */
  function doSomething(foo){...}
}

Thank you for writing an answer. My question however was how to document a function declaration that is not a method of the service. In the code example I gave I would like to find a way to use ngdoc with myFunction (which is not a method). The code example also illustrated use of methodOf being used with myMethod (which is a method). In your example doSomething is a method so it makes sense to use methodOf. — paulhhowells, Oct 09 '15 at 09:40

score 0 · Answer 2 · answered Apr 08 '16 at 21:00

0

I only have experience with JSDoc, not ngdoc, but have you tried @memberOf rather than @methodOf?

Link to JSDoc page for memberOf

answered Apr 08 '16 at 21:00

medievalgeek

165
9

So far I have not found a way with ngdoc to use `@memberOf`, `@member`, or `@private`, to document `myFunction` as being inside the closure of the function that generates `myService`. There’s a fair bit of functionality in JSDoc that doesn’t seem to be available in ngdoc. Thanks for wanting to help. – paulhhowells May 16 '16 at 11:09

score 0 · Answer 3 · answered Jun 16 '16 at 22:51

/**
 * @ngdoc controller
 * @name MyApp.myController:myController
 * @description
 * This is myController controller.
 **/          
angular.module('MyApp').controller('myController', ['$scope', function($scope) {       

  /**
   * @ngdoc function
   * @name myFunction
   * @methodOf MyApp.controller:myController
   * @description
   * This function does something
   */
   function myFunction(){
    // do something
   }

}]);

myFunction is not a method – paulhhowells Jun 17 '16 at 08:57 — paulhhowells, Jun 17 '16 at 08:57

How can ngdoc be used to document a function declaration in an angular service?

3 Answers3