Add support for specifying the TypeScript version

[kpau]

Currently in our project we are using TypeScript 1.5.3.
The latest version is 1.6.0-beta and typedoc is using it.

Is it possible to specify which version to use? I searched the docs but didn't find such option.
Can you add such config?

Thanks!
Kristiyan

[sebastian-lenz]

Hi Kristiyan, nice to hear from you. Did you run into any issues with the new version? Normally the TypeScript compiler is compatible with older versions, they mainly add new features.

It is not possible to use TypeDoc with a different version of TypeScript as the one it was released with. If you check the diff of the compiled version after an update of TypeScript you'll see that mainly due to the constant enumerations used by the compiler the binary is tightly bound to that version.

We could work around the constant enumeration problem by switching to ntypescript. However, ntypescript builds daily from the master branch of TypeScript so as I understand it they already have switched to TypeScript 1.6 too.

Also every new version of TypeScript slightly changes the API we have to use. As TypeDoc pulls things directly from the inner data structures of the compiler this can result in pretty huge changes to our code base. I have to admit the step from v1.5 to v1.6 was pretty easy, on the other hand there have been updates resulting in an entire overhaul like v0.9 to v1.0 and v1.0 to v1.2.

Till TypeScript v1.5 we always waited for the release version from Microsoft to switch to the new compiler version. But since v1.5 the TypeScript team releases beta versions to NPM and we had a discussion on when TypeDoc will finally switch to v1.5. Due to the policy of waiting for the release we did not switch but Microsoft made the beta last for several months and people got a bit angry. So this time I decided to update to the new compiler early in the beta phase.

TL;DR
It is not possible to specify the TypeScript version that TypeDoc should use. You have to stick to a certain version of TypeDoc if you have the need for a particular version of TypeScript. I'm currently unsure myself at what point in TypeScripts release cycle we should update TypeDoc - good ideas are welcome.

[kpau]

Hi Sebastian,
Thanks for the fast response.

We are using gulp-typedoc, and there is no way currently to select the TypeDoc version from it. I've tried to switch to older version of gulp-typedoc, but it still used the latest of TypeDoc .

The problem with the new version of TypeScript comes from the Strict object literal assignment checking.
Maybe adding the support to provide compiler options to TypeScript will help in the current case (by using the --suppressExcessPropertyErrors).
At some point we'll update our code and fix those issues. But I don't think that the version of TypeScript which we are using should depend on the tools and plugins we use.

Updating TypeDoc to use the latest possible version of TypeScript is the preferred way I think.
Maybe this issue should be addressed to gulp-typedoc, and should be added the option to choose the TypeDoc version from there. I have also created issue there.
Meanwhile I'll set ignoreCompilerErrors to true, until option is added or we fix the errors produced from the latest version of TypeScript (whichever comes first).

[sebastian-lenz]

TypeDoc allows you to pass all options available to the TypeScript compiler. gulp-typedoc passes the provided options directly to TypeDoc so when invoking gulp-typedoc you should be able to pass an options object looking like this:

gulp.task("typedoc", function() {
    return gulp
        .src(["data/*.ts"])
        .pipe(typedoc({ 
            suppressExcessPropertyErrors: true
        }));
});

[kpau]

Great!
That should do the job.
Thanks!

[sebastian-lenz]

Great, I'll close this issue for now.