Friendly ping @sandersn .

I'm not sure what is the expected of unittests:: JSDocParsing

Couple of quick comments -- I've only glanced at the code, haven't really read it yet.

1. The jsDocParsing unittests are pretty basic. I think the existing test for @see there is sufficient.
2. The tests I'd like to see are goto-def tests, obviously.
3. My understanding of jsdoc is that braces are not required here since these aren't type references, but we might as well parse them because people may still use them ... and they aren't ambiguous, so why not?

Hoops. Seems not my fault.

UP ↑

I'm sorry, but I don't know how to refer to the methods of a class in the classes' jsdoc comment.

And I'm not sure what is the expected behavior in below case:

function foo (a: string) {
    /**
     * @see {a}
     */
    function bar (a: string) {

    }
}

When we apply goto-def at see tag, It should be linked to function foo or bar ?

The class-method question is a variant of the function-parameter question:

class K {
  m { }
/**
 * Here's how to use C:
 * First, construct it, then call m
 * @see m
 */
class C {
  m() { }
}
}

I'm not sure what to do there either.

Probably we should resolve to the outer declaration. (foo:a and K.m) I'll ask the team to see if anybody else has opinions.

@sandersn Is that a valid syntax?... I'm not sure what are you expected...

@typescript-bot pack this.

Heya @Kingwl, I've started to run the tarball bundle task on this PR at 51b67d7. You can monitor the build here.

Hey @Kingwl, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/83979/artifacts?artifactName=tgz&fileId=9A8F21D752ED3524E8C7785D7AE26622ABF7CCFFE3F5BCDE9FA311FFB577030F02&fileName=/typescript-4.1.0-insiders.20200902.tgz"
    }
}

and then running npm install.

There is also a playground for this build.

Based on my comment on the original bug, here are some more test cases that need to be added. They don't have to pass, but I want to make sure they don't crash:

1. @see Class#method -- this should, ideally, resolve to Class at least.
2. @see {@link M.f} -- doesn't need to work yet.
3. @see M.f() -- should, ideally, resolve to M.f and ignore the trailing ().

I'm going to do a bit more looking to see how well we'll be able to resolve module references in things like lodash. I think a lot of uses just make up a name for the module they are inside, even though it's never declared inside the module itself.

The only question I have left before merging this is how to resolve x here:

/** @param x @see x */
function f(x) { }

Right now, @see x doesn't resolve in the scope of f.

But I don't actually think people write this. I'm going to figure out if that's the case.

Either way, I think the best thing is to resolve starting from the parameter list of a function declaration.

Maybe we could peek the parameters first if jsdoc attached on a function like declaration.
But that will point to two different symbol. Is that ok?

If we resolveName starting from the parameter list, I think you can get it to resolve to just the parameter. So @see on a function should start from the parameter list probably. (or it may be the function itself, although I'd rather not resolve to locals of a function.)