Can tjsdoc be used yet?

[JulianKingman]

I followed the breadcrumbs here from esdoc issues, to your esdoc fork, and then here. I'm having trouble with certain ES6 features, and am mainly just trying to get something to work. I realize this package is in alpha right now, but can it be used? Will it work? If so, do you have a basic example, or any kind of documentation? Thanks! I appreciate your angle on this package, and I think it will help many people.

[JulianKingman]

It looks like, at the very least, references to dist need to move to src, unless there's a secret build process I couldn't find.

[typhonrt]

@JulianKingman thanks for making the trek here! I am actively working on finishing the publishing module presently which is the last step to getting TJSDoc out the door for ES6+. It has taken a bit longer to get out than I originally thought, but I'm taking a no compromise approach to getting things to production quality out of the gate.

I'm currently just wrapping up the theming system which uses PostCSS and allows plugins to create custom themes for the generated docs including all the power of cssnext. The theming effort which I should get posted today and on NPM is located in a separate TyphonJS org: typhonjs-node-theme. This should be the last architecture / utility level work to complete with the remaining work pertaining to final reorganization of the actual generated documentation; see #1. #3 will also be complete before initial launch which is one of the killer features of TJSDoc.

Regarding dist the prepublish script runs tests, eslint and transpiles as an NPM publish hook when npm publish is executed. dist is built in that step and is not checked into the repo.

Do hang in there as TJSDoc will be worth checking out when it drops!

[typhonrt]

@JulianKingman By the way which ES6 features are you having a problem with as I'll make a note in getting them solved?

After initial launch there will be work to complete as I am aiming to have full support for ES6+ / stage 2 code including for instance new support for decorators and anything else that should be captured in documentation. Flow typing will also be supported natively as well which is forthcoming functionality then onto native Typescript support.

[JulianKingman]

I had two main problems. The first was deconstructed objects with default values (e.g. const {a = 0} = b;), and the second was async/await syntax (it gave me an error that await is a reserved word).

I wasn't able to get esDoc to work, even playing around with various plugins, so I went back to jsDoc and managed to get a version of it running. I look forward to a better solution :)

[typhonrt]

In general regarding the async / await syntax error you'll want to check that the function using await is actually marked async otherwise that is the syntax error that is raised with a bare await in a normal function. For ESDoc you may need to enable config settings under experimentalProposal -> asyncGenerators; though I haven't confirmed this. Depending on which version of ESDoc you use it's set in two different ways.

TJSDoc is focused on convention over configuration so there is no experimentalProposal config setting as everything that is stage-2 or higher is enabled by default for the JS / Babylon parser. Given that TJSDoc heavily uses async / await I haven't seen a problem with parsing.

As far as the destructuring issue is concerned are you receiving a runtime error from ESDoc? Is b in your example an object (had to ask the obvious)? What was the concern / problem raised? This should be ES6 code and not cause a problem. object rest / spread is the only special case with ESDoc that requires an experimentalProposal setting.

In the TJSDoc code base destructuring & object rest / spread is used throughout and once again works without having to set any particular config setting when generating docs against the code base.

Out of curiosity what do you not like about jsDoc?

[JulianKingman]

Regarding async / await, everything is as it should be, including the experimentalProposal config. I'm not sure why it wouldn't take it...

For spread operators, there's this specific error: https://github.com/esdoc/esdoc/issues/377, and yes b is an object :)

In general, I'm not super excited about the syntax of jsDoc, it's not very intuitive to me. The thing I would love most is to be able to structure the documentation to mirror my app, instead of just the types of entities. The place this problem is most obvious is with react components, which can be either classes or functions, and are thus put in separate places, even if they are almost the same (and they actually switch sometimes, if a component becomes more or less complex). Beyond that, I'd like to have a hierarchical structure, so that I could have a form component with a path components/form/TextInput (or similar), and have constants next to related functions or classes, etc... jsDoc makes me want to code things in particular ways to have the documentation make sense, like put all related things into giant objects.

[typhonrt]

Weird on the async / await situation; it definitely works w/ TJSDoc out of the box.

I am aware of that particular rest/spread issue with ESDoc. It's fixed in TJSDoc. Interestingly unlike ESDoc TJSDoc will treat those kinds of errors as a runtime error / invalid code warning in a limited section of the runtime and keep chugging along and not cause things to crash, so future language parsing problems are protected in the runtime. There are many improvements in architecture of TJSDoc and considerably better error reporting which pinpoints the 1st or 3rd party module which failed.

Regarding jsDoc that is my general reactions too as the left hand navigation is rather poor. There are big problems with the left hand navigation of ESDoc as well as it groups all doc items by directory without any indication of file they belong to which you might have noticed. I solved this with esdoc-plugin-enhanced-navigation and this is the basis for the default TJSDoc left hand navigation. When you dig a little into how TJSDoc works it's event driven and the left hand navigation is composed by an event. It's totally possible for a 3rd party plugin to unregister the default handler for this event and return a custom left hand navigation experience without having to rewrite all HTML output like older ESDoc plugin has to which is quite annoying / error prone. I might have created the most complex 3rd party ESDoc plugins which exposed a lot of integration pain points which I remedied w/ TJSDoc. It will be quite interesting to see what the larger community will be able to accomplish as well.

A big goal of TJSDoc as well is to take into account the modular world that our code lives in and to take account of modern package managers (NPM, JSPM, WebPack, etc.). I happen to fall on the side of the many-repo approach versus the mono repo, so this is important to me. I don't know of any JS doc tool which can link together docs across modules in a coherent fashion. Everything else out there just works with a single project / code base.

I guess pointing out that TJSDoc also better supports large mono-repos as one can supply multiple source roots and globs to define the source for a project. There are only less than ideal hacks available for ESDoc.

I'll likely close this issue in a day or so, but if you have any thoughts I'd be glad to hear them and look forward to you trying out the initial releases of TJSDoc and providing valuable feedback!

[JulianKingman]

Great, I look forward to it. Drop a message in here when this repo can be used, and I'll try it out.

[typhonrt]

If you can subscribe to #2 I'll be posting low bandwidth updates on progress. It's close though.