如何使用JSDoc注释AngularJS组件

Question

What tag should we use to document an Angular JS component with JSDoc? I was thinking of using @module, am I right?

For example :

/**
* @module helloWorld
*
* @description AngularJS component to display a message with a name.
*
*/
angular.component('helloWorld', {
  bindings: {
    name: '@'
  },
  controller : function helloWorldCtrl () {
    this.logName = logName;

    /**
     * @function logName
     *
     * @param {string} msg - message to display with the name.
     *
     * @memberof helloWorld
     *
     * @description Log in the console the message with the name.
     *
     */
    function logName(msg) {
      console.log(msg + this.name);
    }
  },
  template : '<div><span ng-click="$ctrl.logName('Hi ')">{{$ctrl.name}}!</span></div>'
});

I would have the same question for directive, service and controller. Besides is my way of using @memberof right?

Answer 1

Although JSDoc does have @module , it's a "visibility" specification and I don't think it is what you're looking for.

The @module tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise.

Which might be true, but also might not be.

The key thing you need to remember is that these annotations should act as a breadcrumb trail so that inherited behavior can be linked to in the documentation and also so that the compiler has as much information about the code as possible.

So, when looking for how to document this I'd look up the parts in the Angular externs and @return / @type / @param to match;

@return {angular.Component} Component definition object.

Hope that helps!

Answer 2

First define your separate topic in your documentation to listing all modules. For this create some empty file with next annotation:

/**
 * @namespace solution_name
 */ 

For module can be used this annotation to have each module defined in its seprarate html page

/**
 * @class solution_name.MyModule
 * @memberOf solution_name 
 */

Service annotation to be added as part of myModule page documentation

/**
 * @function myService
 * @memberOf solution_name.MyModule
 * @description This is an my service.
 */

Controller can be decorated like this to be listing also inside your module documentation page as separate unit

/**
 * @class solution_name.MyModule.MyController
 */

To create tree structure to combine controllers, services based on businees needs you can also add namespace attribute per your class/function definition

/**
 * @namespace MyApp.Controllers
 */