Documenting ES6 Code

I’m going a bit crazy right now. We’ve migrated TaskGroup to ES6 (see the es6 branch) and seeing huge performance gains. However, our documentation is written in tomdoc and was passed with biscotto when it was coffeescript. Biscotto doesn’t support anything but javascript.

There is no tomdoc parsers for javascript. And there is no jsdoc parsers that support ES6.

The babel people suggested docchi and documentationjs but I haven’t gotten either to work.

Others have suggested jsdoc and yuidoc, but I haven’t got either to read the ES6 code - they output empty documentation.

The best I’ve found is doxx when using the jsdoc branch of TaskGroup, and got the following output:

Which is okay, definitely not as nice as what biscotto outputted, has issues with the return display and linking to classes, and is incredibly stupid that I have to define what is a function:

	 * A helper method to check if the passed argument is an instanceof a {Task}
	 * @param {Task} item - The possible instance of the {Task} that we want to check
	 * @return {Boolean} Whether or not the item is a {Task} instance.
	 * @function
	 * @public
	static isTask (item) {
		return (item && item.type === 'task') || (item instanceof Task)

And what is a class and what it extends, even if it is written right there in the code:

 * Our Task Class
 * @extends BaseEventEmitter
 * @class
 * @public
class Task extends BaseEventEmitter {

All other tools crashed or generated nothing.

All in all, I’ve tried so far:

And a few others.

If anyone has any suggestions, that would be great, as I’m going more than a bit crazy about this.

I got yuidoc 0.6.0 to work, try this example for yuidoc,

@pflannery just tried with this yuidoc.json file:

    "name": "TaskGroup",
    "description": "Group together synchronous and asynchronous tasks and execute them with support for concurrency, naming, and nesting.",
    "version": "5.0.0",
    "url": "",
    "options": {
        "linkNatives": "true",
        "nocode": true,
        "attributesEmit": "true",
        "selleck": "true",
        "ignorePaths": [ "test" ],
        "paths": "./es6/lib",
        "outdir": "./docs",
        "markdown": "default"

Got a few warnings and an empty output once again. Can you try getting yuidoc working on the jsdoc branch of TaskGroup and let me know how it goes? Otherwise, I’m giving up on YUIdoc.

done try this -

Great thanks. Commit with the magic is here:

It seems even more superflous than the earlier jsdoc code snippets. Hopefully this is the solution that Docchi is promising to solve (I will create an issue to make sure that this is actually the problem that Docchi is solving).

Hopefully we can get either Steve McArthur and his renderer or perhaps your own @pflannery yuidoc renderer to generate from the Docchi json file. Or we open a pull request with YUIdoc to get them to remove the redundancy in the syntax.

Yuidoc has lots advantages, one being your documentation isn’t coupled with your code, large amounts of documentation can obscure the code so it’s nice to have the ability to describe documentation outside of the code file. Another adv. is it works with C++, Javascript, C#, Coffee-script (using ###*) and other languages that have the same commenting syntax. It also allows us to write one documentation template which can render all our different language projects in the same format.

It’s only class names and method names that you have to rewrite. Up to you though, it’s your project :wink:

I’ve opened up and to hopefully remove the superflous tags.

Started the process of yuidoc documentation for TaskGroup. Current progress can be seen here:

:+1: this is looking good

To be honest, that doesn’t really read nicely. jsdocs is almost complete with ES6 support:

I bet you can get away with substituting some of the newer features and still document everything, that way when it is complete, you have a way better solution in the end.

So far we’ve progressed with YUIDocs with this, however has progressed really well and will likely give that a go.

An update on this. We now use across the board.

To get started with our setup, you can use: