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 });
           
    }

Karol Majewski · Answer 1 · 2020-06-24T11:30:19.050

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<P> 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<Payload>, res: Response) {

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

score 1 · Answer 2 · answered Jun 24 '20 at 10:35

1

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.

answered Jun 24 '20 at 10:35

H.B.

166,899
29
327
400

Thanks lemme give it a shot, been seeing this as the only solution with some googling, just wanted to know my options, thanks again – myrdstom Jun 24 '20 at 10:43
See also the answer by Karol Majewski; if you can use generics to type the request more precisely that would be the best option. – H.B. Jun 24 '20 at 11:22

How do you add nested params to tsdoc documentation

2 Answers2