Generating Javascript documentation [closed]

问题:

I'm looking for a way to generate documentation automatically from my Javascript project. Anyone know how can I do this?

As far as I know, there're some tools like JSDoc but I want to know your opinion, your best choice and why.

Thanks!

EDIT: just to be clear, I need something like JavaDOC or PHPDocumentor but to use with my Javascript source code.

回答1:

There are tools like Natural Docs to do this. I've personally used it in the past and this works fine with javascript.

There are also tools like docco to document source code.

In general auto generated documentation tends to be too restrictive and sometimes handmade API's like the jQuery API are easier to use.

Also documentation for dynamic languages is different from documentation on static languages. As API's are used differently and state exist in a more loose sense.

回答2:

I found a great tutorial to create JS documentation using JSDoc. I hope it helps to someone who need it.

Create useful relevant Javascript documentation with JSDoc

This was exactly what I need. Thanks for your answers stackers.

回答3:

If you work with node.js, i created a module that generate class diagram for javascript/node/html/css. Its based on the "WAE" extension of UML. Its called wavi. For javascript, function,variable and use of other modules are automatically recognized. You can use it for documenting your application.

https://www.npmjs.org/package/wavi

回答4:

SmartComments + YUIDocs

Using that extraordinary couple you can document a large JavaScript project in less than one minute.

SmartComments, it’s a tool that allow you to create implicit comments from JavaScript source code.

You can use in the console or through of a Sublime Text Plugin.

Please go to http://smartcomments.github.io for further information.

回答5:

autodoc is teh dope; https://www.npmjs.org/package/autodoc | https://github.com/dtao/autodoc

Autodoc lets you write tests in comments just above your JavaScript functions, then run those tests from the command line and auto-generate documentation with the same tests embedded and executing right in the browser.

Think literate programming, look at http://danieltao.com/lazy.js/docs/ for a nice example. Those green checkmarks are the tests.

✓ Lazy([1, 2, 4])       // instanceof Lazy.ArrayLikeSequence
✓ Lazy({ foo: "bar" })  // instanceof Lazy.ObjectLikeSequence
✓ Lazy("hello, world!") // instanceof Lazy.StringLikeSequence
✓ Lazy()                // sequence: []
✓ Lazy(null)            // sequence: []

This is what the source looks like github.com/../lazy.js#L86

/**
 * Wraps an object and returns a {@link Sequence}. For `null` or `undefined`,
 * simply returns an empty sequence (see {@link Lazy.strict} for a stricter
 * implementation).
 *
 * - For **arrays**, Lazy will create a sequence comprising the elements in
 *   the array (an {@link ArrayLikeSequence}).
 * - For **objects**, Lazy will create a sequence of key/value pairs
 *   (an {@link ObjectLikeSequence}).
 * - For **strings**, Lazy will create a sequence of characters (a
 *   {@link StringLikeSequence}).
 *
 * @public
 * @param {Array|Object|string} source An array, object, or string to wrap.
 * @returns {Sequence} The wrapped lazy object.
 *
 *
 * @examples
 * Lazy([1, 2, 4])       // instanceof Lazy.ArrayLikeSequence
 * Lazy({ foo: "bar" })  // instanceof Lazy.ObjectLikeSequence
 * Lazy("hello, world!") // instanceof Lazy.StringLikeSequence
 * Lazy()                // sequence: []
 * Lazy(null)            // sequence: []
 */

It extends JSDoc https://developers.google.com/closure/compiler/docs/js-for-compiler, so in addition you can have Google's closure compiler verifying and optimising lot of things for you.

回答6:

Which framework are you using ? (if any). I think the tool you'll choose depends a lot on that, since ideally it would have to understand class extensions and all. Otherwise I think jsDoc is a great place to start.

回答7:

Hi i just found YUIDoc. I don't know much about it, but it looks good...