Repository: TypeScript
Issue: JSDoc @augments doesn’t allow function calls to augment existing types
Labels: Suggestion,Domain: JSDoc,Domain: JavaScript,Experience Enhancement

I wrote a simple extension of [jest.Matchers][1] but I can not get the typescript type checker to recognize my extension.

<!-- Please try to reproduce the issue with `typescript@next`. It may have already been fixed. -->
**TypeScript Version:**  3.0.1 (and 3.1.0-dev.20180825)
The description below is for 3.0.1 - for 3.1.0-dev.20180825 all jest functions show errors, so I don't even think that the parser gets to my type at all.
```
[ts] Cannot find name 'describe'.
[ts] Cannot find name 'test'.
[ts] Cannot find name 'expect
```

Used via vscode version: 1.26.1

<!-- Search terms you tried before logging this (so others can find this issue more easily) -->
**Search Terms:**
is:issue is:open jsdoc extends
is:issue is:open jsdoc @augments
is:issue is:open jsdoc "@augments" 

I first asked this as a [question on StackOverflow](https://stackoverflow.com/questions/51972275/jsdoc-document-object-method-extending-other-class) but after waiting a few days, I now suspect it is a bug in typescript's JSDoc implementation.

I also read the FAQ and found [the link](https://github.com/Microsoft/TypeScript/wiki/FAQ#how-do-i-write-unit-tests-with-typescript) to jest but didn't find any information there either.

I'm using plain JavaScript and the code runs perfectly.

**Code**

```js
// @ts-check

const getFunctorValue = F => {
  let x
  F.fmap(v => x = v)
  return x
}


expect.extend({
  /**
  * @extends jest.Matchers
  * @param {*} actual The functor you want to test.
  * @param {*} expected The functor you expect.
  */
  functorToBe(actual, expected) {
    const actualValue = getFunctorValue(actual)
    const expectedValue = getFunctorValue(expected)
    const pass = Object.is(actualValue, expectedValue)
    return {
      pass,
      message () {
        return `expected ${actualValue} of ${actual} to ${pass ? '' : 'not'} be ${expectedValue} of ${expected}`
      }
    }
  }
})

/**
* @param {*} v Any value
*/
function just (v) {
  return {
    fmap: f => just(f(v))
  }
}

describe('Functor Law', () => {
  test('equational reasoning (identity)', () => {
    expect(just(1)).functorToBe(just(1))
  })
})
```

**Expected behavior:**
`expect().functorToBe` should be recognized as a function.

**Actual behavior:**
But in the line with `expect(just(1)).functorToBe(just(1))`,
I get a red underline under `functorToBe` and the following error message:

>[ts] Property 'functorToBe' does not exist on type 'Matchers<{ [x: string]: any; fmap: (f: any) => any; }>'.
any

I got `jest.Matchers` from writing `expect()` in [vscode][2] and looked at the description.

[![image of vscode intellisense displaying jest.Matchers as return type for expect()][3]][3]

**Playground Link:** <!-- A link to a TypeScript Playground "Share" link which demonstrates this behavior -->

**Related Issues:** <!-- Did you find other bugs that looked similar? -->
No.

[1]: https://jestjs.io/docs/en/expect#expectextendmatchers
[2]: https://code.visualstudio.com/
[3]: https://i.stack.imgur.com/fvwKY.png