JSDoc

Question

我们正在使用 Webstorm 和 JSDoc 来提供一些不错的建议功能，并在需要时提供类型文档。

例如，这是 User 的定义，在整个应用程序中多次使用。

/**
     * Basic user object
     * @typedef {Object} User
     * @property {!Number} id - Unique identitifaction
     * @property {!String} email - Email and username in once
     * @property {!Boolean} enabled - True, if user can access the system
     * @property {!Boolean} confirmed - True, if validation (i.e. through email) was successfull
     *
     * @property {?String} name - Name of user
     */

那我们就可以用他来举例服务方式，根据用户的一些细节来选择

/**
 * return Detail of user
 * @param {User} params
 * @param {Options=} options
 * @returns Promise.<User>
 */
exports.userDetail = (params, options = {}) => {
    return userRepository.userDetail(params, options);
};

到目前为止，它的效果非常好，当我在 exports.userDetail 方法中使用 params 时，它会自动建议我们可以使用的字段。

问题是"on the top of tree"。例如，详细信息的标准 CRUD 操作是使用此方法并仅通过 id

选择

/**
 * @param {Number} req.userId
 */
exports.detail = (req, res, next) => {
    return userService.userDetail({id: req.userId}).then(user => {
        res.out = user;
        return next();
    }).catch(next);
};

然而在这部分{id: req.userId} webstorm调用错误：'Argument type ... is not assignable to parameter type User'

唯一的解决办法是命名所有属性，否则它会这样说。对于其他情况，此警告确实很有帮助 - 它会发现，如果您将 Number 错误地放入字符串中，或者将 Token 错误地放入 User 等。但是，将真正的错误与这个错误混合在一起会使它变得不那么可靠。

有人对一般的 JSDoc 或 Webstorm 有一些建议吗？我没有找到如何说 "This parametr is user even without all the fields, not all of them are mandatory".

的方法

另一方面，我想在整个应用程序中共享一个模型 - 我可以在每个功能上编写完整的定义，它可以正常工作

/**
 * Register standard user
 * @param {String} _params.email Unique email for registration, used also instead of username
 * @param {String} _params.password Password for your account
 * @param {Options=} options
 */

但是当我们在很多方法中使用 User 时，每次更改都意味着在整个应用程序中更新它需要做很多工作（当它变得足够大时几乎不可能）

Answer 1

您可以尝试将属性定义为可选 - 例如

/**
     * Basic user object
     * @typedef {Object} User
     * @property {!Number} id - Unique identitifaction
     * @property {!String} [email] - Email and username in once
     * @property {!Boolean} [enabled] - True, if user can access the system
     * @property {!Boolean} [confirmed] - True, if validation (i.e. through email) was successfull
     *
     * @property {?String} name - Name of user
     */

JSDoc - 部分创建的类型定义

JSDoc - type definition with partial creation

javascript

documentation

node.js

webstorm