Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

undefined as module name and export= as property name #1907

Closed
jackens opened this issue Apr 4, 2022 · 1 comment
Closed

undefined as module name and export= as property name #1907

jackens opened this issue Apr 4, 2022 · 1 comment
Labels
bug Functionality does not match expectation

Comments

@jackens
Copy link

jackens commented Apr 4, 2022

Search terms

module name, export name, undefined, export=

Expected Behavior

The documented module has the correct name (instead of undefined).
The documented property has the correct name (instead of export=).

Actual Behavior

The documented module has an invalid name (undefined).
The documented property has an invalid name (export=).

Steps to reproduce the bug

typedoc.json:

{
  "cleanOutputDir": true,
  "entryPointStrategy": "expand",
  "entryPoints": [
    "src"
  ],
  "hideLegend": true,
  "out": "_doc",
  "readme": "none"
}

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "module": "commonjs",
    "outDir": "tmp",
    "target": "esnext"
  },
  "include": [
    "src/**/*.js"
  ]
}

package.json:

{
  "dependencies": {
    "typedoc": "0.22.13",
    "typescript": "4.6.3"
  }
}

src/file.js

/**
 * @module someModuleName
 */

/**
 * @name someName
 */
module.exports = { answer: 42 }

Executing

npm i
npx typedoc

generates a file _doc/index.html with module name undefined and property name export=.

Environment

  • Typedoc version: conf. package.json
  • TypeScript version: conf. package.json
  • Node.js version: v14.17.4
  • OS: MacOS
@jackens jackens added the bug Functionality does not match expectation label Apr 4, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Apr 9, 2022

The documented module has the correct name (instead of undefined).

This happens because, for the package, TypeDoc takes the name from your package.json file, unless you override it with --name. TypeDoc should probably warn you about this if the name isn't set... With a single file, it seems reasonable to me to infer the name from the file, but we'd still run into issues with multiple files, and when TypeDoc is given a directory, it doesn't have that file at the point the package name is defined... it's probably best for TypeDoc to just give a warning for now, it's an easy configuration setting to fix.

The documented property has the correct name (instead of export=).

TypeDoc does not support renaming reflections with @name. You could write a plugin to do this:

// typedoc --plugin ./path/to/this/file.js
const td = require("typedoc");

exports.load = function (app) {
    app.converter.on(td.Converter.EVENT_CREATE_DECLARATION, onDeclaration);
};

/**
 * @param {td.Context} _context
 * @param {td.Reflection} reflection
 */
function onDeclaration(_context, reflection) {
    const rename = reflection.comment?.getTag("name");
    if (rename) {
        reflection.name = rename.text.trim();
        reflection.comment.removeTags("name");
    }
}

@Gerrit0 Gerrit0 closed this as completed in 934206d Apr 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Functionality does not match expectation
Projects
None yet
Development

No branches or pull requests

2 participants