使用JsDoc3创建AngularJS文档的问题

Question

I have an AngularJS factory that I am trying to generate documentation for using Jsdoc. The logic is below:

(function (angular) {

    /**
    * @module factories
    * @memberOf angular_module
    */
    var factories = angular.module('factories');

    /**
    * @class BaseService
    * @classdesc Base object
    * @param {Object} $rootScope Root scope for the application.
    */
    factories.factory('BaseService', ['$rootScope', function ($rootScope) {

        var baseObject = (function () {

            // Prototype
            var basePrototype = {

                _construct: function (args) {

                },

                publicMethod: function (args) {                    

                }
            };

            // 'Private' methods
            function initialise(args) {

            }

            function privateMethod(param) {

            }

            function setObjectProperties(o, properties) {
                for (prop in properties) {
                    if (properties.hasOwnProperty(prop)) {
                        o[prop] = properties[prop];
                    }
                }
            }

            //-----------------------------------------------
            return {
                create: function (args, properties) {
                    function obj() { }
                    obj.prototype = basePrototype;
                    var o = new obj();

                    setObjectProperties(o, properties);

                    // Call the base object 'constructor'
                    o._construct(args);              
                    return o;
                }
            };
        })();

        return  {

            /**
            * @function create
            * @memberof! BaseService
            * @description Creates a new object
            */
            create: function (args, properties) {
                return baseObject.create(args, properties);
            }
        };
    }
    ]);

    /** 
    * @class ChildService
    * @classdesc Child object
    * @extends BaseService
    */
    factories.factory('ChildService', ['BaseService', function (BaseService) {
        return BaseService.create({ 'someProperty': true }, {
            /**
            * @function childPublicMethod
            * @description Child public method
            */
            childPublicMethod: function () {
                return this.publicMethod(123);
            }
        });
    }]);

}(angular));

In another file I have:

/**
* @namespace angular_module
*/

The problem I am having is I would like to generate documentation for the BaseService.create method as part of the BaseService documentation. Similarly I would like to generate documentation for the ChildService.childPublicMethod function in the ChildService section. However currently nothing is created for BaseService.create, and the documentation for ChildService.childPublicMethod is added to the factories module. I have tried using @lends and @alias, as well as all sorts of combinations of modules/class names as part of the @memberof line, but nothing thus far has given me the desired outcome. Any suggestions gratefully received.

Answer 1

The solution I have come up with is as follows:

(function (angular) {

    /** 
    * @namespace factories
    * @memberof angular_module
    */
    var factories = angular.module('factories');

    /**
    * @class BaseService
    * @classdesc Base object
    * @param {Object} $rootScope Root scope for the application.
    * @memberof angular_module.factories
    */
    factories.factory('BaseService', ['$rootScope', function ($rootScope) {
        var baseObject = (function () {

            // Prototype
            var basePrototype = {

                _construct: function (config) {

                },

                /**
                * @function publicMethod
                * @description Creates a new object
                * @memberof angular_module.factories.BaseService
                */
                publicMethod: function (args) {                    

                }
            };

            // 'Private' methods
            function initialise(args) {

            }

            function privateMethod(param) {

            }

            function setObjectProperties(o, properties) {
                for (prop in properties) {
                    if (properties.hasOwnProperty(prop)) {
                        o[prop] = properties[prop];
                    }
                }
            }


            //-----------------------------------------------
            return {
                create: function (args, properties) {
                    function obj() { }
                    obj.prototype = basePrototype;
                    var o = new obj();

                    setObjectProperties(o, properties);

                    // Call the base object 'constructor'
                    o._construct(args);              
                    return o;
                }
            };
        })();

        return  {
            /**
            * @function create
            * @description Creates a new object
            * @memberof angular_module.factories.BaseService
            */
            create: function (args, properties) {
                return baseObject.create(args, properties);
            }
        };
    }
    ]);

    /** 
    * @class ChildService
    * @classdesc Child object
    * @memberof angular_module.factories
    * @extends angular_module.factories.BaseService
    */
    factories.factory('ChildService', ['BaseService', function (BaseService) {
        return BaseService.create({ 'someProperty': true }, {
            /**
            * @function childPublicMethod
            * @description Child public method
            * @memberof ChildService
            */
            childPublicMethod: function () {
                return this.publicMethod(123);
            }
        });
    }]);

}(angular));

Here's the changes:

1. I replaced the @module declaration for the 'factories' variable with @namespace

2. I added @memberof angular_module.factories to the class declarations.

3. I prefaced the values for the @extends and @memberof tags with angular_module.factories.

Really hope this helps someone out.