Documentation for Namespaces Shadows Documentation for Functions

[bradharms]

Steps to reproduce / Current Behavior

On https://loopback.io/doc/en/lb4, in some places where a link refers to a symbol which is both a namespace and a function, there is only a link to the function form of a symbol and not the namespace, even where the context of the documentation refers to the function form of the symbol. This makes it seemingly impossible, or at least unintuitive, to access the documentation for many functions which shares a name with a namespace through the main online documentation. (This is not a universal issue, however, as there are a few places where both links are present side by side.)

Expected Behavior

Any link that refers to a symbol as a function within the current context of the documentation should actually link to the page for the documentation about the function, and not the page for the documentation about the symbol. This should be true whether the link appears in a directory listing, as well as links that appear within inline documentation content.

Examples

Here are some notable function/namespace links as they appear within their parent listing. There may be other examples, and I do not know to what extent this issue occurs among inline thinks.

• In @loopback/context: bind(), inject(),
• In @loopback/openapi-v3: param()

One counter-example where the issue was explicitly avoided, albeit in a somewhat awkward way considering the namespace form is listed under both the "functions" heading and the "namespace" heading:

• In https://loopback.io/doc/en/lb4/apidocs.repository.html: repository()

Additional Comments

I've had this issue bite me several times. Usually I work around it by cloning loopback-next locally and look at the source code, but it's really nice to be able to access the docs in online html form and I'd like to be able to do it consistently.

I don't know exactly how docs are generated but, I'd think there would be a way to explicitly indicate function forms when that is the intent and vice versa. Or possibly merge the pages for symbols with the same name, as that would be consistent with the programmer experience and would automatically eliminate the issue everywhere all at once.

[raymondfeng]

AFAIK, it's a known issue with Microsoft API Extractor.

[bradharms]

AFAIK, it's a known issue with Microsoft API Extractor.

I see. This issue seems to be another instance of the same bug.

Do you recommend waiting for the extractor to be fixed?

[dhmlau]

@bradharms, if that's the case, is it ok to close this issue since there's not much we can do here. Thanks.