TypeScript support

[sebald]

Hi there,

is it possible to use documentation with TypeScript? If not, are there any plans to support it?

[tmcw]

We've started documenting Flow compatibility in GETTING_STARTED https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md#flow-type-annotations but need more TypeScript examples, as well as a bit of context for what's the overlap & difference between the two syntaxes.

The gist is that documentation.js is able to infer parameter types from Flow type annotations, so that you can omit JSDoc-style type descriptions. It can also transform typedef statements into typedefs in documentation, again with inferred property types. The technical guts of this transformation are in flow_doctrine, that translates typeAnotation AST nodes (as parsed by Babel) into type objects like doctrine would export.

[tmcw]

Reading into this, we do need to make it clear that the scope is supporting TypeScript type annotations, where they overlap with Flow and not support for everything in TypeScript. Babel can't parse TypeScript, so we can't.

[tmcw]

Babel listed TypeScript support in the potential future plans of their update. It's probably still a ways out, though, and as before Babel's support is necessary for documentationjs's support.

[tmcw]

I'm going to make the call to cut TypeScript support as a TODO right now. I'd be happy and overjoyed to review and accept a PR implementing support, but given the mountain of other things to work on, it isn't something I can realistically say I can do in 2017.

[abarisain]

Hi!

Babylon supports typescript if you enable the matching plugin. It works really well: prettier's typescript support is based on it.

I'll try updating documentationjs' babylon version, and parsing settings. As I am unfamiliar with how this project works, do you think this will be enough, or would it require significant changes to code using the parser?

[arv]

It depends on what AST we get. Is there an overlap between the Flow an TS AST?

[abarisain]

Unfortunately, it seems not.

They're quite different, so I guess another doctrine would be required?

Here is the partial result for a simple test class:

test.js
------
// @flow

var test: string;

class Foo {
    bar: string;

    test(arg1: string, arg2: string): string {
        return 2;
    }
}

export default Foo;

test.ts
------
// test comment

var test: string;

class Foo {
    bar: string;

    public test(arg1: string, arg2: Number): Number {
        return 2;
    }
}

export default Foo;

(This requires babylon@7.0.0beta, and you can't use the "flow" and "typscript" plugins at the same time)

[abarisain]

So, I gave it a shot and it looks like there's a lot of work figuring out what the AST looks like before getting something out.
Getting familiar with documentationjs' codebase at the same time certainly isn't helping me (not that it's bad or anything!).
I'll post an update here whenever/ifever I get something working.

I don't think that the issue should be reopened.
Thanks for the fast reply!

[Almenon]

For those looking for a typescript documentation generator there is one here.

Though even if you are using typescript you can still run documentation on your generated js file.
I just did that over at arepl-backend

[StoneCypher]

typedoc is really weak, and doesn't support almost any of what you need in a real documentation generator. can't even make public and private documentation

in the meantime typescript has mostly won, and is expected to represent es8's possible type system

[giladgray]

@tmcw what would it take to add typescript support today (generally, not specifically today)? would be very cool to use this on one of my large typescript codebases, so i'm motivated to contribute but i don't know where to start?

it seems like babylon's support for typescript may have improved, so perhaps this is worth reinvestigating.

[tmcw]

Sure, that's be great! I can't be 100% of sure what's required without implementing it, but what I expect is:

• Parse TypeScript. See src/parsers/javascript: it'd be like that, using a TypeScript-compatible parser
• Switch to that parser when a file has a .ts extension - see src/index.js for an example of how we swap between vue & js parsers when we see a .vue extension. It'd be the same idea.
• Translate TypeScript to doctrine expressions for types - see src/flow_doctrine.js for how we currently translate Flow annotations to doctrine.
• Tweak the inference steps (src/infer/) for any differences between the TypeScript AST and the JavaScript AST, if there are any.

I'm not up-to-speed on step (1), whether babylon is now good at TypeScript parsing. If so - and if that's only in babylon 7, that means this task would encompass #996, the update to the Babel 7 ecosystem.

[scharf]

TSDoc may be interesting in this context. See also Format TSDoc: A TypeScript Source Code Documentation Format.