Skip to content

Commit e07b6d4

Browse files
authored
Merge pull request #60 from Daniel-Knights/module-resolution-improvements
Module resolution improvements
2 parents 2c97d56 + 22e5fbf commit e07b6d4

File tree

4 files changed

+184
-110
lines changed

4 files changed

+184
-110
lines changed

README.md

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,23 +10,14 @@ JSDoc accepts plugins by simply installing their npm package:
1010

1111
To configure JSDoc to use the plugin, add the following to the JSDoc configuration file, e.g. `conf.json`:
1212

13-
```json
13+
```jsonc
1414
"plugins": [
1515
"jsdoc-plugin-typescript"
1616
],
17-
"typescript": {
18-
"moduleRoot": "src"
19-
}
2017
```
2118

2219
See http://usejsdoc.org/about-configuring-jsdoc.html for more details on how to configure JSDoc.
2320

24-
In the above snippet, `"src"` is the directory that contains the source files. Inside that directory, each `.js` file needs a `@module` annotation with a path relative to that `"moduleRoot"`, e.g.
25-
26-
```js
27-
/** @module ol/proj **/
28-
```
29-
3021
## What this plugin does
3122

3223
When using the `class` keyword for defining classes (required by TypeScript), JSDoc requires `@classdesc` and `@extends` annotations. With this plugin, no `@classdesc` and `@extends` annotations are needed.
@@ -40,31 +31,36 @@ TypeScript and JSDoc use a different syntax for imported types. This plugin conv
4031
### TypeScript
4132

4233
**Named export:**
34+
4335
```js
4436
/**
4537
* @type {import("./path/to/module").exportName}
4638
*/
4739
```
4840

4941
**Default export:**
42+
5043
```js
5144
/**
5245
* @type {import("./path/to/module").default}
5346
*/
5447
```
5548

5649
**typeof type:**
50+
5751
```js
5852
/**
5953
* @type {typeof import("./path/to/module").exportName}
6054
*/
6155
```
6256

6357
**Template literal type**
58+
6459
```js
6560
/**
6661
* @type {`static:${dynamic}`}
6762
*/
63+
```
6864

6965
**@override annotations**
7066

@@ -73,13 +69,15 @@ are removed because they make JSDoc stop inheritance
7369
### JSDoc
7470

7571
**Named export:**
72+
7673
```js
7774
/**
7875
* @type {module:path/to/module.exportName}
7976
*/
8077
```
8178

8279
**Default export assigned to a variable in the exporting module:**
80+
8381
```js
8482
/**
8583
* @type {module:path/to/module~variableOfDefaultExport}
@@ -89,26 +87,37 @@ are removed because they make JSDoc stop inheritance
8987
This syntax is also used when referring to types of `@typedef`s and `@enum`s.
9088

9189
**Anonymous default export:**
90+
9291
```js
9392
/**
9493
* @type {module:path/to/module}
9594
*/
9695
```
9796

9897
**typeof type:**
98+
9999
```js
100100
/**
101101
* @type {Class<module:path/to/module.exportName>}
102102
*/
103103
```
104104

105105
**Template literal type**
106+
106107
```js
107108
/**
108109
* @type {'static:${dynamic}'}
109110
*/
110111
```
111112

113+
## Module id resolution
114+
115+
For resolving module ids, this plugin mirrors the method used by JSDoc:
116+
117+
1. Parse the referenced module for an `@module` tag.
118+
2. If a tag is found and it has an explicit id, use that.
119+
3. If a tag is found, but it doesn't have an explicit id, use the module's file path relative to the nearest shared parent directory, and remove the file extension.
120+
112121
## Contributing
113122

114123
If you are interested in making a contribution to the project, please see the [contributing page](./contributing.md) for details on getting your development environment set up.

0 commit comments

Comments
 (0)