Allow back predefined "files" order when using the files option

[dmnsgn]

Description
While fixing a new glob behaviour, the introduction of input files sorting modifies the behaviour if you pass files defined in a specific order.

Commit: 7083d03#diff-d7ec8b2f1fcf6a2e2af8a75e28d6800d4dfe8ac6b6d35a6faf3034e36ba51d08

Problematic code:

jsdoc-api/lib/jsdoc-command.js

Lines 45 to 47 in 4d06895

	/* node-glob v9+ (used by file-set) no longer sorts the output by default. We will continue to sort the file list, for now, as it's what the user expected by default. The user's system locale is used. */
	const collator = new Intl.Collator()
	this.inputFileSet.files.sort(collator.compare)

I hope I tracked this issue correctly and it is not something unrelated to the above 🙏

Use case
I am sorting files before doing a jsdoc2md.render() in jsdoc-to-markdown so I can get docs generated in an order that makes more sense than alphabetical.

Issues

• breaks generated docs order in jsdoc-to-markdown since v9.3.0
• it is not possible to define a custom order for generated docs (afaik)
• isn't using new Intl.Collator() making it potentially platform dependent, if it is related to the computer locale?

Solutions

• add a filesSort option
• sort file-set per array items instead of the final this.inputFileSet.files?

[75lb]

Hi, thanks for the report. Assuming I can reproduce this it will be considered a bug - there was no intention to break custom sort order. Will look into it.

[75lb]

I've added the ability to sort glob expansion results in file-set, which jsdoc-api will make use of - should be finished soon.

isn't using new Intl.Collator() making it potentially platform dependent, if it is related to the computer locale?

It's not platform-dependent (it works the same on windows, mac and linux) but yes the current behaviour respects the user's locale. Which is typically what non-Americans want (the V8 engine is American-by-default, which doesn't suit say Russian speakers as I've mentioned before). What is the behaviour you would prefer to see?

[dmnsgn]

Nice one. Using a sort function for each of the options.files instead of the final inputFileSet.files is all I need really.
I am personally fine if it relies on current locale in file-set for each of the options.files, but maybe other users of jsdoc-api would want to customise it with a locale option?

[75lb]

Fixed and released in jsdoc-api v9.3.5, also included in jsdoc-to-markdown. Could you give it a quick check please.

but maybe other users of jsdoc-api would want to customise it with a locale option?

Well, they've not yet asked for that in 11 years but if they do I will add it.

[dmnsgn]

Yes it works as it used to. Thank you!