Documenting ES6 Code

infrastructure
Tags: #<Tag:0x00007f10eaa6f160>

#1

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.


#2

I got yuidoc 0.6.0 to work, try this example for yuidoc, https://gist.github.com/pflannery/5291f51c3ca39c48164c


#3

@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": "https://github.com/bevry/taskgroup",
    "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.


#4

done try this - https://github.com/pflannery/taskgroup/tree/yuidoc


#5

Great thanks. Commit with the magic is here:
https://github.com/pflannery/taskgroup/commit/44acd77c1223fd5e6b43454bb346727372c45035

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 https://github.com/SteveMcArthur/docpad-api-documentation or perhaps your own @pflannery yuidoc renderer https://github.com/pflannery/yuidoc-theme-dyno 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.


#6

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:


#7

I’ve opened up https://github.com/yui/yuidoc/issues/336 and https://github.com/yui/yuidoc/issues/337 to hopefully remove the superflous tags.


#8

Started the process of yuidoc documentation for TaskGroup. Current progress can be seen here:
https://rawgit.com/bevry/taskgroup/es6/docs/index.html


#9

:+1: this is looking good


#10

To be honest, that doesn’t really read nicely. jsdocs is almost complete with ES6 support: https://github.com/jsdoc3/jsdoc/issues/555

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.


#11

So far we’ve progressed with YUIDocs with this, however http://documentation.js.org has progressed really well and will likely give that a go.


#12

An update on this. We now use http://documentation.js.org/ across the board.

To get started with our setup, you can use: