typedoc.js vs typedoc.json configuration files in documentation

[Rolias]

• [X] I have checked issues with bug label and found no duplicates

Expected Behavior

The documentation will mention a typedoc.json file in one spot and a typedoc.js file in another. For instance, in the example page for arguments and when running help from the command line, the --options flag indicates that if a file isn't specified it will look for typedoc.jsfile. Further down on the documentation page under the --options sections it contradicts that and says that by default it will look for a typedoc.json file.

Actual Behavior

Make clear if the config file should be .json or .js or if both are acceptable. If both are acceptable which is the default. I was trying to specify both an out:"docs" setting and a tsconfig location setting. I could not get a typedoc.json file to work. I was able to get a typedoc.js file to work. Also, it would be helpful to show a .js example since I believe the config data needs to to be wrapped with

module.exports = {
}

Steps to reproduce the bug

Nothing to do just read the docs and the command line --help output.

Environment

• Typedoc version:0.14.2
• Node.js version:10.15.3
• OS: macOS

[aciccarello]

I would say that typdoc.json is the preferred option. typedoc.js is supported for backwards compatibility, but if you need to define options dynamically, using the programmatic API is preferred.

Thanks for raising this issues about the confusing documentation and the issues you were encountering with typedoc.json.

[aciccarello]

If we can verify the typedoc.json tsconfig option issue we should have a separate story so we can track the documentation and the bug separately.

[Rolias]

I think it's really just a documentation issue. I got the .js config file working yesterday so today I converted that to a .json file and it worked fine. I must have had some other problem in the config file. Since both versions work this is of pretty low importance. If you have deprecated support for .js then I still think it would be good to update the documentation. Personally, I prefer .js config files because I can add comments in there.

[Gerrit0]

Cross linking #1074 here. If we do continue supporting .js and .json files, we should probably rename the default filename to typedoc.config.js to avoid unexpected behavior on Windows. Unfortunately, the rename is a rather large breaking change. Most projects that use TypeDoc that I'm aware of use a typedoc.json or typedoc.js file for options.

[aciccarello]

You probably could support both typedoc.js and typedoc.config.js` but I'd rather drop support than maintain a list of possible config files. If someone wants to have a dynamic config, the programatic api is fairly straightforward and well documented.

[Gerrit0]

The docs have been updated with #1085, website docs have also been updated and will be pushed momentarily.

[Tyoneb]

Hey guys!

The docs have been updated with #1085, website docs have also been updated and will be pushed momentarily.

I don't know if the website update was missed but the options page still references the JS config file and I stumbled upon the issue with the opening of the JS file in an editor mentioned in #1074.
It would be good to have the documentation updated on the website to clarify the supported options.
Thanks!

[Gerrit0]

It would be good to have the documentation updated on the website to clarify the supported options

Both typedoc.js and typedoc.json are supported for now, the docs were just updated to place the JSON file first, I haven't started actively discouraging typedoc.js since I don't yet understand all the reasons that people pick the dynamic option instead of the static JSON.

[Tyoneb]

Oh okay, my bad, I thought it was planned to remove the support of the JS config file because it doesn't work properly if named typedoc.js. To bring some insight on my use case, I don't use any dynamic JS, I just tend to prefer static JS files compared to static JSON because of the way they are written/displayed (allow trailing commas, don't force double quotes on properties, etc) But maybe that's just me and my OCD ^^

[dannyrb]

FWIW, I'll often pick the .js option if only to allow // comments