Tools and guide for documenting TypeScript code?

问题:

Are there any tools for generating documentation for TypeScript source code? Or should I use something generic like NaturalDocs? What would be the recommended style of the block comments / those intended for standalone volume of documentation.

Should I use:

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

or

/** @javadoc style comments */

or perhaps

/*
  Something like this?
 */

I'm afraid to use /// because it is used for imports, and I don't want to tread on some other future feature possibly introduced in the similar way - but you never know...

Or is it possible to generate documented JavaScript from TypeScript and then use the JavaScript toolchain?

回答1:

Maybe a bit late but after I came across this problem I found there were still no tools to do this. So I forked the TS compiler and created the code to do it.

Forked TypeScript compiler project at v0.9.0.1 then added a "--documentation" option that will generate wiki documentation from whatever JSDoc you put in the code (none required for just plain output of methods/properties etc. )

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

It produces .ts.wiki files (contents of which is suitable for uploading straight to CodePlex etc. if you also use the new --wikiRemoveRoot and --wikiSourceRoot params as well - see fork - my first commit description). Or you could adapt the code to produce HTML (which would be relatively simple - I've done the hard work of mangling the compiler/delcrationEmitter :) )

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

Ed

回答2:

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

The documentation generator runs the TypeScript compiler and extracts the type information from the generated compiler symbols. Therefore you don't have to include any additional metadata within your comments.

If you want to try it out, simply 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 a documentation created with TypeDoc looks like, head over to the GitHub page of the project:

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

回答3:

You can use this kind of commenting above your function.

/** 
* Comment goes here
*/

And next when you will hit your method it will show up with documentation.

回答4:

Generate XML Doc comments one of the proposed issues for TypeScript language.

For now TypeScript tools support JSDoc Announcing TypeScript 0.8.2.

So, you definitely want to use JSDoc style for comments. If you need comments only for IntelliSense - using JSDoc will cover your requirement. If you need comments because you want to provide documentation for your API consumers - you should use declaration files (*.d.ts) with comments. If you want to generate nice documentation on web - I guess it will be easy to just wait when TypeScript team will implement generation of XML doc comments (or write it by hand).

回答5:

I'm compiling to JavaScript and use jsduck (https://github.com/senchalabs/jsduck) to generate api documentation based on the JavaScript files. As long as you don't tell tsc to remove comments that works perfectly, except of 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's 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

回答6:

I've written a tool for generating HTML documentation from declaration (.d.ts) files here. It has basic support for JSDoc-style comments.

Compile your TypeScript source files with the -d -c options to generate declaration files and preserve comments. Then after installation, you can run

typescript-docs *.d.ts

to generate HTML documentation on standard output.

To save output to a file, use

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