使用JSDoc记录工厂 [英] Documenting factories with JSDoc

问题描述

为了避免在我的JavaScript代码中使用 new ，我编写工厂来创建对象。

In order to avoid using new in my JavaScript code, I write factories to create objects.

I我尝试了很多种组合，而且给我最满意的结果如下：

I have tried many combinations and the one that gives me the most satisfactory result is the following:

/**
 * Document module
 * @module app/document
 */
(function () {
    'use strict';

    /**
     * Factory that creates a document object.
     * @alias module:app/document.factory
     * @return {document}
     */
    function document() {
        /**
         * Get document id
         * @method id
         * @return {String}
         */
        var id = function id() {...},
            api = {
                id: id
            };

        return api;
    }

    /**
     * This module exports the {@link module:app/document.factory|factory} function.
     */
    module.exports = document;
}());

这些评论的问题是没有文件对象定义。因此，我无法在另一个对象中引用此对象，并且在扩展此对象时我无法继承其文档。

The problem with these comments is there is no document object defined. Therefore, I can't reference this object in another object and I can't inherit its documentation when I extends this object.

以什么方式记录此类对象对象？

What is the appropriate way to document this kind of object?

如果我使用 @typedef 标签，我会得到静态工厂方法
和文档对象正确记录
但没有 id 方法文档由JSDoc生成：

If I use the @typedef tag, I get the static factory method and the document object properly documented but no id method documentation is generated by JSDoc:

/**
 * Document module.
 * @module app/document
 */
(function () {
    'use strict';

    /**
     * Factory that creates a document object.
     * @function module:app/document.factory
     * @return {document}
     */
    function factory(agent) {
        /**
         * @callback document~id
         * @returns {String}
         */
        var id = function id() {...},

            /**
             * @typedef document
             * @property {document~id} id
             */
            document = {
                id: id
            };

        return document;
    }

    module.exports = factory;
}());

推荐答案

我给你的建议是很好地定义出口您的模块使用@typedef定义类型，然后使用@type {FactoryDe​​finition}注释module.exports = factory

My recommendation to you is to well define the exports on your module using @typedef to define the type and then annotate the module.exports = factory with @type {FactoryDefinition}

 /** @typedef {{ id: !string }} */
 var DocumentDefinition;

 /** @typedef {!function(!object):!DocumentDefinition} */
 var FactoryDefinition;

/** @type {FactoryDefinition} */
module.exports = factory

这篇关于使用JSDoc记录工厂的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！