Documentation

[fredck]

The API and guides documentation solution we'll adopt in CKEditor 5 must be discussed and implemented.

[fredck]

In v4 we're using JSDuck, which is still a good option.

After a 10 mins research, not much has been found. The only that caught my eyes is JSDoc 3. Found a comparison of it with others.

[Reinmar]

Yeah... I did the research too few weeks ago and nothing caught my eyes except JSDuck. We may not be happy with its complexity and the fact that its written in Ruby, but I don't see any option to use any other solution without seriously modifying it, what may be similarly or even more costly for us.

JSDuck is really powerful and, while digging in its internals, I also felt that it's well designed and written, so it is possible to modify it in reasonable time. There are of course some problems like SEO, but the truth is that for the last year or more we didn't have time to check that for real.

[mlewand]

In fact JSDoc is an interesting option, which is I guess the most known annotation standard out there.

JSDuck is now pretty much dead and burried for quite some time as opposed to JSDoc which keeps sustainable, healthy status.

JSDuck has some problems:

• it's written in yet another language (ruby) and comes with a big dependency (most painful is sencha sdk, that tends to be unavailable for weeks)
• it's not popular, therefore some of IDE are missing support for it (hate to see @memberOf rather than @member in my code complete :( )
• poor markup in the output (eg. in API tree some links are div with click listeners)

The downside is ofc that we would need to make a beautiful styling for new docs rather than using the default one.

If we're looking for adding features, it looks like JSDoc is even pretty extensible allowing us to add whatever we like.

Since CKEditor will be rewritten for the most part, it's a good moment to improve our annotations.

JSDoc comes with all sort of goodies, like grunt task etc, so that's making it so much easier to integrate into our workflow.

[Reinmar]

(most painful is sencha sdk, that tends to be unavailable for weeks)

? WFM.

JSDuck is now pretty much dead and burried for quite some time as opposed to JSDoc which keeps sustainable, healthy status.

3 years ago JSDuck also was super healthy and it reached a level of feature-completeness which makes it very useful and powerful. Most likely it's also a reason why the development slowed so much. Not every tool in the world needs to be continuously changed. BTW. Note that most of the issues have replies from the maintainer - https://github.com/senchalabs/jsduck/issues.

Anyway, if we want to consider JSDoc, we need:

• either find examples of rich and cute JSDoc implementations for big docs (note - we'll have hundreds classes again),
• or dig deep into JSDoc to learn what's possible.

[Reinmar]

(most painful is sencha sdk, that tends to be unavailable for weeks)

? WFM.

Aaaand it doesn't work for me any more. Moreover, I checked the whole picture more closely and it doesn't look that well. Sencha apparently doesn't maintain old stuff well - I couldn't find anything about Sencha SDK tools, including any information about changelog, previous versions. Pretty much nothing.

Therefore, I would, as Marek proposed, consider JSDoc. However, it seems that we'll need to build something more rich around it, so it's not all roses too.

[gregpabian]

I'm for JSDoc3 as well (been using it for years), though it will require some amount of work to make the output good looking and easy to use. Anyway, +1 here.

[Reinmar]

I've spent few minutes googling and I haven't found a single good looking theme :D. Another thing is what I mentioned earlier - our docs are huge comparing to the examples I can find. So not only we'll need proper theme, but entire UI. This will be a pretty big project itself :D.

[fredck]

Hum... things got more complicated now, since we decided to go ahead with ES6.

I've found this so far: https://esdoc.org/

[Reinmar]

I've just stumbled upon http://documentation.js.org/

[Reinmar]

After performing review existing tools we chose JSDoc for which we're preparing our own theme. That said... JSDoc is buggy and not well maintained but at the time it looked best anyway.