jsdoc icon indicating copy to clipboard operation
jsdoc copied to clipboard

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

Open l0ner opened this issue 2 years ago • 15 comments

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

l0ner avatar Feb 03 '23 15:02 l0ner

Relatedly, jsdoc also doesn't generate documentation for non-default exports (as brought up in #1517)

Higgs1 avatar Feb 22 '23 16:02 Higgs1

Something definitely changed... This use to work with JSDOC V3

It seems that adding @function corrects this behavior in JSDOC V4, but adding another decorator is painful.

Maybe #2023 has the same issue.

z3dev avatar May 14 '23 02:05 z3dev

CKEditor has in theri jsdoc plugins a hacky way that fixes this by replacing all export default* and export class in the source before it gets parsed:

https://github.com/ckeditor/ckeditor5-dev/blob/master/packages/jsdoc-plugins/lib/export-fixer/export-fixer.js

l0ner avatar May 17 '23 07:05 l0ner

Very annoying, the problem is still exists: https://stackoverflow.com/questions/41311557/jsdoc-not-recognizing-exported-function

JSDoc 4.0.2

robozb avatar Jun 07 '23 17:06 robozb

I was able to get it to work with the @method

jweird avatar Aug 03 '23 04:08 jweird

I was able to get it to work with the @method

So what! This is still a BUG. A BIG FAT BUG!

It seems that adding https://github.com/function corrects this behavior in JSDOC V4, but adding another decorator is painful.

z3dev avatar Aug 03 '23 13:08 z3dev

seems to be duplicate with #1132

Also note that it does not work with objects too:

/**
 * @type {Something} 
 */
export default {
  something: ""
};

while this is working:

/**
 * @type {Something} 
 */
const something = {
  something: ""
};
export default something;

gsouf avatar Jul 03 '24 10:07 gsouf