Merge pull request #60 from Daniel-Knights/module-resolution-improvements

Module resolution improvements

Author: ahocevar

README.md

@@ -10,23 +10,14 @@ JSDoc accepts plugins by simply installing their npm package:
 
 To configure JSDoc to use the plugin, add the following to the JSDoc configuration file, e.g. `conf.json`:
 
-```json
+```jsonc
 "plugins": [
   "jsdoc-plugin-typescript"
 ],
-"typescript": {
-  "moduleRoot": "src"
-}
 ```
 
 See http://usejsdoc.org/about-configuring-jsdoc.html for more details on how to configure JSDoc.
 
-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.
-
-```js
-/** @module ol/proj **/
-```
-
 ## What this plugin does
 
 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
 ### TypeScript
 
 **Named export:**
+
 ```js
 /**
  * @type {import("./path/to/module").exportName}
  */
 ```
 
 **Default export:**
+
 ```js
 /**
  * @type {import("./path/to/module").default}
  */
 ```
 
 **typeof type:**
+
 ```js
 /**
  * @type {typeof import("./path/to/module").exportName}
  */
 ```
 
 **Template literal type**
+
 ```js
 /**
  * @type {`static:${dynamic}`}
  */
+```
 
 **@override annotations**
 
@@ -73,13 +69,15 @@ are removed because they make JSDoc stop inheritance
 ### JSDoc
 
 **Named export:**
+
 ```js
 /**
  * @type {module:path/to/module.exportName}
  */
 ```
 
 **Default export assigned to a variable in the exporting module:**
+
 ```js
 /**
  * @type {module:path/to/module~variableOfDefaultExport}
@@ -89,26 +87,37 @@ are removed because they make JSDoc stop inheritance
 This syntax is also used when referring to types of `@typedef`s and `@enum`s.
 
 **Anonymous default export:**
+
 ```js
 /**
  * @type {module:path/to/module}
  */
 ```
 
 **typeof type:**
+
 ```js
 /**
  * @type {Class<module:path/to/module.exportName>}
  */
 ```
 
 **Template literal type**
+
 ```js
 /**
  * @type {'static:${dynamic}'}
  */
 ```
 
+## Module id resolution
+
+For resolving module ids, this plugin mirrors the method used by JSDoc:
+
+1. Parse the referenced module for an `@module` tag.
+2. If a tag is found and it has an explicit id, use that.
+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.
+
 ## Contributing
 
 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.