Resolve @typedef imports and const requires.

[nodech]

Plugin from: https://github.com/SoftwareBrothers/better-docs#typedefimport

This will allow typedefs like, which are supported by many tools:

/** @typedef {import('./path')} Path */
/** @typedef {import('./walletdb')} WalletDB */

That are not valid jsdoc (yet), so this plugin removes them before the jsdoc parses them.

Alternative way to use them "properly" for the docs is:

/**
 * @param {module:wallet.WalletDB} wdb
 * @returns {module:wallet.Path}
 * /
function somefn(wdb) {...}

But is not well supported by other tools, so completion etc will fail for most. But returns reference guide generated by the jsdoc tools.

So summary:
I believe @typedef {import} to be more widely adopted by the tools. Even though this does not improve reference guide generated by the docs.
module:wallet.WalletDB does improve the reference, but does not help the tools.

[nodech]

Added another plugin: https://github.com/polyforest/jsdoc-tsimport-plugin

Which instead of just removing, tries to expand them into proper module: form. This sounds like better of both worlds, so decided to include.

From the issue jsdoc/jsdoc#1645

[nodech]

Unfortunately, tsimport does not seem to be properly using aliases for the reference. Generates links but they are not linking to anything.

[nodech]

Okay, implemented a version where imports are expanded into their aliases if those aliases were detected by the jsdoc and were properly exported. It may miss some export types, have not worked out all I think, but POC good and it is way better in both ways: better jsdoc, better tooling.

E.g. with this plugin you can add this line after requires (does not really matter) in TXDB:

/** @typedef {import('../primitives/tx')} TX */

and every mention of TX will be properly resolved by the tools and will also have CORRECT link to the TX in the reference. Still probably some cases this wont handle, but well.

Note: modify jsdoc.json and add this as plugin:

  ....
  "plugins": [
    "plugins/markdown",
    "plugins/import-aliases"
  ],
  ...

[nodech]

Now const .. = require('./something') should automatically become aliases for those names and can be used locally from the local names. That's what most editors expect them anyway, not longname aliases (module:primitives.MTX)

NOTE: It only supports simple syntaxes:

  const Something1 = require('./something');
  const Something2 = require('./something').SomethingElse;
  const {Something3} = require('./something');
  // more complex cases are not supported.

Ideally we would only use these forms on documentation pages.