Parse @param from comments blocks when using the CLI plugin

[adaliszk]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe it

As a Developer, when I'm using the compiler plugin, I wish that it would read the @param JsDoc/TsDoc from the code blocks of methods so that I would not require to add an @ApiParam decorator just to describe a parameter for the generated API specification.

The documentation briefly touches on the capabilities of the comment block, mentioning that only description and examples work at the moment. There is also a related Automatically detect optional Query (#30) that should be considered when implementing this.

Describe the solution you'd like

when using introspectComments: true with the code:

/**
 * This comment is already working as the "description" field
 *
 * @param limit The amount of items to be returned
 */
@Get()
myMethod(@Query('limit') limit: number) {}

the generated Open API specification would fill out the description for that param automatically.

Teachability, documentation, adoption, migration strategy

The documentation is pretty straitforward at the moment, I think an addition with a table to list all the supported JsDoc/TsDoc annotations would be a nice. With that, a link to raise a new feature request for more annotations could be added.

The migration stategy is a simple replacement:

  /**
   * This comment is already working as the "description" field
   *
+  * @param limit The amount of items to be returned
   */
  @Get()
- @ApiParam({name: 'limit', description: 'The amount of items to be returned'})
  myMethod(@Query('limit') limit: number) {}

This JsDoc/TsDoc annotation usually already generated by most IDEs, so for the most part it would be only removal of the decorator.

What is the motivation / use case for changing the behavior?

Most IDEs already auto-generate the @param JsDoc/TsDoc and they keep it up to date while the custom decorator is not maintained automatically. Furthermore, the annotation is shorter, and its purpose is to serve as the documentation description that is used by many tools outside of Nest JS.

For Code-Quality use case,
this would mean less bloat for filling out descriptions, thus easier overviewability of the code. When a decorator is needed for custom behaviour, then it becomes much easier to spot as all decorator usages will be the advanced cases.

For Tool Integrations use case, such as documentation or specification generators,
this would mean that the CLI plugin alignes with third parties automatically, as there would be a single source of truth for at least the description. Some custom behaviours may still differ, but those are special cases usually.

[kamilmysliwiec]

Would you like to create a PR for this issue?

[adaliszk]

@kamilmysliwiec
Would you like to create a PR for this issue?

I can, however, it might take a bit to familiarize myself with the code here.
Could you point me to the place where the description is parsed from the code blocks?

[andrewda]

Additional tags from TSDoc would be super useful, too. For example, @deprecated can replace @ApiOperation({ deprecated: true }) and @ApiProperty({ deprecated: true }).

[malliaridis]

What is the current state of supporting @param? I faced the same need and wanted to raise a request, accidentally in the wrong project (see nestjs/nest#11409).

Worth noting that there is also a minor bug related to parameter descriptions that contain line breaks and getting added to the function description (see referenced issue).

[kamilmysliwiec]

#1720