[Docs] Generated API docs are missing keywords, descriptions, etc.

[shimks]

Go to apidocs.loopback.io and click on the latest versions of docs for @loopback/rest. From v15 to most recent, the page for the documentation is blank.

Additionally, run npm pack @loopback/rest, unpack the tar, and observe that index.html is essentially blank.

[kjdelisle]

@shimks I don't know the exact cause, but I can say that it's definitely something to do with how strong-docs and TSDoc interact.

I've played around with the latest version of TSDoc and hacked in a script to generate documentation for parts of the loopback project with better results than we currently see.

• Missing interfaces were filled out
• Some doc bodies that were being omitted were now showing up
  and so on...

@strongloop/loopback-devs I'm proposing that we drop strong-docs entirely from loopback next and use TSDoc in its current form first, then leverage its customizability to reskin the docs to fit our upcoming theme.

[bajtos]

I'm proposing that we drop strong-docs entirely from loopback next and use TSDoc in its current form first, then leverage its customizability to reskin the docs to fit our upcoming theme.

In principle, I am happy to drop a tool we have to maintain ourselves and use an off-the-shelf variant maintained by a wider community.

Before we commit to this particular change, I'd like to better understand which features of strong-docs we will lose. For example, strong-docs may support additional annotations like @private, @header and @promise that TSDocs most likely don't support. We should review our loopback-next code for usages of such annotations and make sure we replace them with TSDoc alternatives as part of the migration.

[bajtos]

@raymondfeng could you please check if your recent work in strong-docs has fixed this problem?

[kjdelisle]

I can confirm that as of this comment, the issues have still not been addressed!

• Descriptions are missing from...just about everything!

• What few there are have formatting problems:

  **from packages/rest/api-docs/index.html#InvokeMethod**
  Invokes a method defined in the Application Controller
  
  Returns:
  OperationRetval Result from method invocation
  

My vote is that we switch to TypeDoc and do whatever is required to customize the formatting of those templates (CSS/images/etc), rather than attempt to fix the strong-docs package to compensate for these issues. I don't expect that we'll find a quick fix for much of these issues, and based on my own experience using TypeDoc directly, most of these problems will disappear instantly.

[kjdelisle]

I'd also add that we should begin preparing for the split between the old documentation site and the "new" one (which will be reskinned with the new design/logo/etc)