Loopback-next: docs: Missing @param() decorator API Docs

[virkt25]

https://apidocs.strongloop.com/@loopback%2fopenapi-v2/v/0.1.0/

The above API Docs is missing documentation for the @param decorator but the docs have documentation for other decorators such as @get(), @post(), etc.

The decorator is documented in code. Seems like the tool generating the Docs is failing to parse it correctly possibly because the decorator is @param which is also reserved for documenting is as well.

[kjdelisle]

For beta, we have the http://loopback.io/doc/en/lb4/Decorators.html#parameter-decorator section, which provides some detail on how to use the @param decorator.

Until we have a proper fix for the typedoc parsing issue, we should avoid making hacky fills in the regular documentation (or anywhere, really!)

[bajtos]

A possible alternative to tsdoc: https://github.com/angular/dgeni-packages/commit/3e07adee84b7a795a0fb02d7181effa593fb9b4f and https://github.com/angular/dgeni

[dhmlau]

related to: https://github.com/strongloop/loopback-next/issues/989

[raymondfeng]

My theory is that param is used for both the decorator function and a namespace (@param.path.string). The same issue happens to inject (@inject and @inject.getter).

[raymondfeng]

This has been mostly fixed by https://github.com/strongloop/strong-docs/pull/108 and https://github.com/strongloop/strong-docs/pull/109.

There is one issue left - https://github.com/TypeStrong/typedoc/issues/472

[jannyHou]

Thank you @raymondfeng !
I add a comment here just to remind myself update @param and @requestBody doc in https://github.com/strongloop/loopback-next/pull/1145 when the namespace/function detect issue is fixed.

[bajtos]

Blocked - waiting for https://github.com/TypeStrong/typedoc/issues/472

[raymondfeng]

I fixed it with a workaround by https://github.com/strongloop/loopback-next/pull/1328