Apidocs are not being built correctly

[shimks]

Description / Steps to reproduce / Feature proposal

Plenty of documentation in our apidocs is broken at the moment. Taking authentication for example:

• No entry on AuthenticationBindings
• docs above StrategyAdapter constructor are not generated
• docs for PassportRequest are not generated, although the sidebar entry is
• @description and @example (above AuthenticateActionProvider) are not honored

We should keep this issue open to address the apidocs-generation issue as a whole. Here's what I think should be done:

• identify what areas are broken
• fix the generation engine (easier said than done 😆)
• verify that all intended docs for apidocs get generated correctly

IMO, this should replace #1171

---

UPDATED (11/27)
From the 4 problems listed in the original description, 2 are already fixed.

Acceptance Criteria

• Fix the problem: docs for PassportRequest are not generated, although the sidebar entry is
• Fix the problem: @description and @example (above AuthenticateActionProvider) are not honored
• Based on the investigation/fix for the 2 problems, create a new issue to review/fix similar problems in other packages

See Reporting Issues for more tips on writing good issues

[shimks]

I'd be also ok with closing this issue if we repurpose #1171 to also address similar issues for other packages as well

[dhmlau]

@shimks , are we going to close this as fixed because of #111 or as dup of #1171?

[shimks]

@dhmlau I think the scope of this issue is a superset of #1171, and although I don't think it should be closed but I can see why we could since we don't know if there's anything that's blatantly amiss about the apidocs

[dhmlau]

Cross posting the comment from #1908 (comment) that there are 2 more issues in apidocs:

• Sequence.md:- Request - (TBD) missing API
  navigating through the apidocs of the rest package, the Request brings to this link http://apidocs.loopback.io/@loopback%2fdocs/rest.html#Request but there is no content. Need to investigate
• Sequence.md:- Response - (TBD) missing API
  navigating through the apidocs of the rest package, the Response brings to this link http://apidocs.loopback.io/@loopback%2fdocs/rest.html#Response but there is no content. Need to investigate

[raymondfeng]

No entry on AuthenticationBindings

Fixed. See http://apidocs.loopback.io/@loopback%2fdocs/authentication.html#AuthenticationBindings

docs above StrategyAdapter constructor are not generated

Fixed. See http://apidocs.loopback.io/@loopback%2fdocs/authentication.html#StrategyAdapter.

docs for PassportRequest are not generated, although the sidebar entry is

No more PassportRequest is in code base.

@description and @example (above AuthenticateActionProvider) are not honored

TBD.

[raymondfeng]

Sequence.md:- Request - (TBD) missing API
navigating through the apidocs of the rest package, the Request brings to this link http://apidocs.loopback.io/@loopback%2fdocs/rest.html#Request but there is no content. Need to investigate
Sequence.md:- Response - (TBD) missing API
navigating through the apidocs of the rest package, the Response brings to this link http://apidocs.loopback.io/@loopback%2fdocs/rest.html#Response but there is no content. Need to investigate

Request and Response are imported from express. I'm not sure what's the best way to link to artifacts from external modules.

[jannyHou]

@raymondfeng the links above don't exist any more. Do you mean the "request" and "response" type in the handlerContext?
http://apidocs.loopback.io/@loopback%2fdocs/rest.html#HandlerContext
Their docs look good actually.

[dhmlau]

@hacksparrow , i believe you had investigated a bit on the outstanding items. Any updates on this? Thanks.

[dhmlau]

Talked to @raymondfeng, the "Request" and "Response" type are imported from Express but our generated apidocs have dangling links. It's a nice-to-have to fix it, but not critical.

This task covers a few issues where the critical ones are fixed. I'm closing this as done and open a new issue for this nice-to-have issue, so that we get the right priority for the task.