jsdoc / jsdoc/jsdoc

JSDoc does not generate documentation for functions and classes exported as default ES module export

Open
#2,038 15 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
15.5k
Forks
1.5k
Avg merge
10d 23h
Merged PRs (30d)
1

Description

Input code

File functions.js

/**
 * Example function, default export.
 * @param {string} arg - String to print.
 */
export default function foo(arg) {}

File classes.js

/**
 * Exported as default class.
 */
export default class FooClass {
	/**
	 * FooClass constructor.
	 *
	 * @param {string} message - Additional message.
	 */
	constructor(message) {
		super();

		/** Some class member */
		this.message = message;
	}

	/**
	 * This is a class method.
	 *
	 * @param {any} someArg - An arg you need to pass.
	 */
	classMethod(someArg) {
		this.fooAClassMethod(this.message);
	}
}
JSDoc configuration
{
	"source": {
		"include": [
			"src",
			"README.md"
		],
		"includePattern": ".+\\.js(doc|x)?$",
		"excludePattern": "(^|\\/|\\\\)_"
	},
	"sourceType": "module",
	"opts": {
		"private": false,
		"recurse": true
	}
}

Expected behavior

In the generated documentation I get FooClass under Classes and foo under Global.

Current behavior

Instead of the expected FooClass i get exports under Classes, and in Global classMethod which is a method of the FooClass.

Instead of getting foo in global I get nothing.

These are the doclets that get passed to the template (warning, wide table is wide):

(index) id name kind type scope memberof undocumented desc longname params filename lineno columnno
0 'astnode100000002' 'exports' (should be FooClass) 'class' 'ClassDeclaration' 'static' 'module' true undefined 'module.exports' undefined 'classes.js' 4 1
1 'astnode100000003' 'exports' (should be FooClass) 'class' 'ClassDeclaration' 'static' 'module' true 'Exported as default class.' 'module.exports' undefined 'classes.js' 4 16
2 'astnode100000006' 'exports' (should be FooClass) 'class' 'MethodDefinition' 'static' 'module.exports#module' (should be FooClass) true 'FooClass constructor.' 'module.exports#module.exports' 1 'classes.js' 10 1
3 'astnode100000003' 'exports' (should be FooClass) 'class' 'ClassDeclaration' 'static' 'module' undefined 'Exported as default class.' 'module.exports' 1 'classes.js' 4 16
4 'astnode100000015' 'message' 'member' 'Identifier' 'instance' 'module.exports' (should be FooClass) undefined 'Some class member' 'module.exports#message' undefined 'classes.js' 14 2
5 'astnode100000020' 'classMethod' 'function' 'MethodDefinition' 'global' undefined (should be FooClass) undefined 'This is a class method.' 'classMethod' 1 'classes.js' 22 1
6 'astnode100000035' 'exports' (should be foo) 'function' 'FunctionDeclaration' 'static' 'module' undefined 'Example function, default export.' 'module.exports' 1 'functions.js' 5 1
7 'astnode100000036' 'foo' 'function' 'FunctionDeclaration' 'global' undefined true undefined 'foo' 0 'functions.js' 5 16
8 undefined undefined 'package' undefined undefined undefined undefined undefined 'package:undefined' undefined undefined undefined undefined

Notice:

  • Index 0, 1, 3: FooClass declaration, but with wrong name (exports instead of FooClass)
  • Index 2: FooClass constructor, but with wrong name (exports instead of FooClass) and memberof (module.exports#module instead of FooClass) and marked as undocumented despite having a documentation.
  • Index 4: FooClass member, but with wrong memberof (module.exports instead of FooClass)
  • Index 5: FooClass metod, with wrong memberof (undefined instead of FooClass)
  • Index 6: foo function, with wrong name (exports instead of foo)
  • Index 7: foo function, but marked as undocumented and with no description or params.
Your environment
Software Version
JSDoc JSDoc 4.0.0 (Thu, 03 Nov 2022 18:37:15 GMT)
Node.js v18.13.0
npm 8.19.3
Operating system Ubuntu 20.04.5 LTS running in WSL under window 11

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue with the functions.js and classes.js examples and inspect the generated doclets. Trace how default ES module exports are represented, then verify that the generated documentation names foo and FooClass correctly, preserves constructor and member relationships, and includes their descriptions and parameters.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.