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 {
{
"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.
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).
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
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.
this is looking good
