Tools and guidelines for documenting TypeScript code?

Question

Are there any tools for creating documentation for TypeScript source code? Or should I use something in common, such as NaturalDocs? What would be the recommended style of comment blocks / intended for autonomous documentation volume.

Should I use:

///<foo>bar</foo> MSVS kind of comments? 

or

 /** @javadoc style comments */ 

or maybe

 /* Something like this? */ 

I am afraid to use /// because it is used for import, and I do not want to step on some other future functions that may be introduced in a similar way, but you never know ...

Or can you create documented JavaScript from TypeScript and then use the JavaScript toolchain?

Answer 1

Perhaps a little late, but after I ran into this problem, I found that there were no tools for this yet. So I forced the TS compiler and created the code for this.

I started the TypeScript compiler project in version v.0.9.0.1, then added the "-documentation" parameter, which will generate wiki documentation from any JSDoc that you entered into the code (none is required for simple output of methods / properties, etc. .)

https://typescript.codeplex.com/SourceControl/network/forks/EdwardNutting/TypeScriptDocumentationGeneration

It creates .ts.wiki files (the contents of which are suitable for loading directly into CodePlex, etc., if you also use the new parameters --wikiRemoveRoot and --wikiSourceRoot - see fork - my first description of the fix). Or you could adapt the code to create HTML (which would be relatively simple - I did the hard work of distorting the / delcrationEmitter compiler :))

Hope this helps (you or future readers of this question)

Ed

Answer 2

I just released a tool called TypeDoc that generates html api documentation pages from TypeScript * .ts files.

The documentation generator starts the TypeScript compiler and extracts type information from the generated compiler characters. Therefore, you do not need to include any additional metadata in your comments.

If you want to try, just install and run the tool through npm:

 npm install typedoc --global typedoc --out path/to/documentation/ path/to/typescript/project/ 

If you want to know what the documentation created with TypeDoc looks like, go to the project’s GitHub page:

http://typedoc.org/ | https://github.com/TypeStrong/typedoc

Answer 3

You can use such a comment on your function.

 /** * Comment goes here */ 

And then when you hit your method, it will appear with the documentation.

Answer 4

Generating XML Doc comments is one of the suggested problems for TypeScript.

At the moment, TypeScript tools support JSDoc declaration of TypeScript 0.8.2 .

So, you definitely want to use the JSDoc style for comments. If you need comments only for IntelliSense - using JSDoc will meet your requirements. If you need comments because you want to provide documentation for your API users, you should use the declaration files (* .d.ts) with comments. If you want to create good documentation on a website, I think it will be easy to wait for the TypeScript command to generate comments on XML documents (or write them manually).

Answer 5

I am compiling JavaScript and use jsduck ( https://github.com/senchalabs/jsduck ) to create api documentation based on JavaScript files. Until you specify tsc to remove comments that work just fine, except for fields without a default value (!).

 module example { /** * My class description * @class example.MyClass */ export class MyClass { /** * Description of my property * @property {String} myProperty */ myProperty: string = null; /** * This property will be removed in compiled JavaScript, that why * this documentation will not be visible in jsduck. */ willNotWork: string; /** * Description of my method * @method myFunction * @param {String} myParam */ myFunction(myParam: string): void { } } } // end of module 

Answer 6

I wrote a tool for creating HTML documentation from declaration files (.d.ts) here . It has basic JSDoc style comment support.

Compile TypeScript source files with the -d -c options to create declaration files and save comments. Then after installation you can run

typescript-docs *.d.ts

to create HTML documentation on standard output.

To save the output to a file, use

typescript-docs *.d.ts --output=path/to/output.html