RFC: Syntax for "declaration references" (hyperlinks)

Certain tags such as {@inheritdoc} contain references to other API items. AEDoc supports two notations for API item references:

• For internal references, we use: exportName.memberName

  Example: {@inheritdoc BaseWidget.draw}

  The “.memberName” is optional and included e.g. if the API item is a member of a class or interface.

• For external references, we use: @scopeName/packageName:exportName.memberName

  Example: {@inheritdoc @microsoft/widget-lib:BaseWidget.draw}

  The “@scopeName/” and “.memberName” are optional. The “@scopeName/” is used for scoped NPM packages.

This might be a reasonable starting point. However, it doesn’t consider nesting members such as namespaces (which has turned out to be surprisingly common for legacy SDKs, despite all the downsides and attempts to deprecate them).

Also, AEDoc today overlooks an interesting edge case:

export class A {
    public b: string = 'hello';
}

export namespace A {
    export let b: number = 123;
}

let a = new A();

// a.b is a string
// A.b is a number

In this example, an expression such as {@link A.b} would be ambiguous. Which declaration is it referring to? How to handle this?

[DaSchTour]

I like option 2 because it looks like URL hashtag. Like an anchorlink it points to a section of a bigger package/file.

[RA80533]

Will the upcoming private fields readily follow such syntax?

• Container.#id (private static)
• Container##id (private instance)

Per sec. 4 of the proposal:

This proposal allows both abbreviated references to private state (#x) which have an implicit this as the receiver, as well as explicit receivers (obj.#x). The implicit receiver form is intended for better ergonomics for the common case, and the explicit receiver form allows the full generality of “class-private” (as opposed to “instance-private”).