How do you add nested params to tsdoc documentation

Question

The code below shows functionality that can potentially be used to register a user. The request body takes in multiple nested parameters such as firstName, lastName, and more. How can I adequately document these nested parameters with tsdoc?

    /**
     * @remarks
     * This method creates a user.
     *
     * @param  req - The request object
     * @param  res - The response object
     *
     * @returns Created user object showing the created user
     * ```
     *{
        "message": {
            "_id": "5ef3249f6a01c1006e091f92",
            "id": "1u_RGoYwV",
            "firstName": "test",
            "lastName": "User",
            "password": "$2a$10$ZQf23Qx910iJLzHO65BOO.RShufiU.YAT/IXnGQwreQ0rdoElrSQG",
            "email": "test@gmail.com",
            "avatarUrl": "https://www.image.com/cat.jpg",
    *       }
     *  }
     * ```
     *
     */

    async create(req: Request, res: Response) {
        let user = new UserModel(this.db);
        const {
            firstName,
            lastName,
            email,
            password,
            currentOrganization,
            avatarUrl
        } = req.body;
        const hashedPassword = await PasswordHelper.hashPassword(password);
        user.setFirstName(firstName);
        user.setLastName(lastName);
        user.setEmail(email);
        user.setPassword(hashedPassword);
        user.setAvatarUrl(avatarUrl);
        user.setCurrentOrganization(currentOrganization);
        await user.save();
        const users = user.get();
        res.status(200).send({ message: users });
           
    }

user_10325032 · Answer

Judging by the usage, I assume your Request and Response represent not the native Request and Response types, but the ones provided by Express.

The express.Request

type accepts a type argument P. This type represents the parameters provided in the request.

The easiest way to provide (and document) them is by creating an interface:

interface Payload {
  /**
   * First name of the user.
   */
  firstName: string;
  lastName: string;
  email: string;
  password: string;
  currentOrganization: string;
  avatarUrl: string;
  [index: string]: string;
}

Feed that interface to your method:

async create(req: Request, res: Response) {

The provided params will be accessible under req.params — they will also have inline docs!

user_546730 · Answer

Declare an interface, document the properties there and reference the interface in the function.

Note that cross referencing (e.g. using @see and @link) does not appear to be well supported in general in editors. Though just having the name there may help people find the interface.

How do you add nested params to tsdoc documentation

2 Answers