References to methods that are both instance and static

[jonchardy]

Say I have some class with an instance and static method of the same name:

export class Foo {
  ...
  public bar() { }
  public static bar() { }
  ...
}

and some reference to it within documentation of another class:

/**
 * See [[Foo.bar]].
 */
export class Baz {
  ...
}

Is there some way for TypeDoc to reference one of these particular methods? Currently, it seems to link to the first one. In JSDoc, this was done by using {@link Foo#bar} vs {@link Foo#.bar}.

[aciccarello]

@jonchardy I don't think TypeDoc supports that currently. I honestly would like to see the links syntax aligned with JSDoc.

[jonchardy]

I've been looking into this some more, and it turns out the @link tag works, but it works in the same way as the brackets, meaning you'd have to say {@link Foo.bar} rather than JSDoc's standard {@link Foo#bar}. I agree that the link syntax should work just as JSDoc does, as that's what people would expect when coming to TypeDoc.

I'll see if I can start some work on fixing the way links are parsed and also address the static issue in the process, as that's linked to JSDoc syntax.

[aciccarello]

It should be noted that TypeDoc was not designed to have 100% parity with JSDoc, but I would be good with aligning the links tag. Thanks for all your investigation and work!

[jonchardy]

PR #514 submitted! --edit: just found more documentation on @link syntax in JSDoc, and it raises some complications...

[jonchardy]

Ok, some notes on this, as it turns out to be pretty complicated and I won't have time to complete a robust solution...

{@link Foo#bar} links to an instance member
{@link Foo.bar} links to a static member
{@link foo.Bar.baz} links to a static member within some class in a namespace

Parsing these to pass to the findReflectionByName method is not a simple task, as we can't easily distinguish when we are looking for a static method without having more information about the structure of Reflections. We can't naively insert some token when we see '.' since it also gets used for namespaces. There probably need to be bigger changes than just updating the MarkedLinksPlugin.

[nrser]

Hey, just taking TypeDoc out for a spin and hit this almost immediately. Did this issue get abandoned? How are people dealing with this?

BTW, I think I like the [[...]] syntax... I never really took to JSDoc & friends' {@link ...}-style, always felt bulky to me.

[jonchardy]

We wrote something custom to handle it that works for our use cases. I don't think anyone is currently working on a general solution that matches the JSDoc spec.

PR #514 linked above may be enough to get it working for you, although I'd expect you would need to adapt it for your own needs.

[aciccarello]

FYI, in the future we'll probably align with the emerging tsdoc standard of Declaration reference, however that is a long way off.