Module resolution improvements

README.md

@@ -10,22 +10,24 @@ 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"
+  "moduleRoot": "src" // optional
 }
 ```
 
 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.
+If `typescript.moduleRoot` is specified, the plugin will assume module ids are relative to that directory and format them as such. For example, `@type {import("./folder/file").Class}` will be converted to `@type {module:folder/file.Class}`. The file extension is removed along with any leading `../` segments (if the referenced module is outside `moduleRoot`).
 
-```js
-/** @module ol/proj **/
-```
+In the absence of `typescript.moduleRoot`, the plugin will mirror the method JSDoc uses to assign module ids:
+
+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.
 
 ## What this plugin does
 
@@ -40,31 +42,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 +80,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,20 +98,23 @@ 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}'}