Write docs for 5.0.0

[connor4312]

A WIP but it's coming along.

It was suprisingly easy to hook up esdoc, sadly though it can't take advantage of the TypeScript typings themselves. There is a generator for TypeScript, Typedoc, but that doesn't seem up-to-par and many serious TypeScript projects like RxJS use esdoc with manual docblocks as well.

[connor4312]

I intended to have a build out today, but a bit more work needs to be done for documentation and I missed converting a couple methods (retention policy stuff) from the previous version. Probably will end up releasing Friday. You can see the live docs site here: https://node-influx.github.io/

[dandv]

Docs look so sweet I was tempted to insert some animated GIF meme right in this comment.

[connor4312]

Gifs are OK! 😄

[schankam]

I upgraded to influx 1.0.2 and looks like the v4 is not working anymore with it. Looking forward for this release !

[connor4312]

Hey @schankam, I saw one other person mention that v4 worked with Influx 1.0. Is there something specific or some error that's thrown with 1.0.2? Want to make sure any discrepancy is resolved in 5.x 😄

[schankam]

Well, I was using 1.0.0 with v4, then I updated to 1.0.2 and it stopped working. I am trying to write a point, but the callback is never fired and I got no error message (and nothing is inserted). Maybe I am doing something wrong somewhere, because I also think it does not make sens (cause 1.0.0 to 1.0.2 should be minor changes not related to the API). I will investigate more and give you my feedback !

[connor4312]

Okay, thanks! I'll be sure to grab and build of 1.0.2 and test it as well before release.

[dandv]

Writing points to Influx 1.0.2 with v4 works for me...

[connor4312]

Resolved in the linked PR. Ran into some more incompatibilities where functionality ported from 4.x didn't work (not sure if that's because it was broken in 4.x or because Influxs' API changed). Merged the PR and will npm publish in the morning.

[dandv]

After delving into the docs, I'm a little less impressed with ESDoc:

• its own docs really need an English-speaking editor
• the punctuation of its docs is rather random (no spaces before parens, sometimes, for example); somewhat surprising for a documentation generator
• the links to methods are absolute
• tilde in the URLs is odd
• no link to edit the doc on GitHub - really core feature IMO
• no line numbers in some cases

[typhonrt]

Hi @dandv et al. I'm an outside contributor to ESDoc. I'd like to gather some requirements for how ESDoc can be improved to support TypeScript and Flow at the same time. As things go ESDoc is switching to Babylon for AST parsing in the forthcoming v1.0 release. I have an experimental fork of ESDoc which currently supports Babylon. I have prototyped (but not released) basic support as a proof of concept which picks up the inline typing in ESDoc output for methods when explicit documentation is missing.

I'd like to hear some thoughts on these basic questions before adding more commentary:

• Babylon only has a plugin for Flow typing, but on a cursory overview it seems Typescript & Flow share the same inline type structure. Is this the case?
• What additional documentation annotations should be supported?
• Outside of picking up inline type information what other enhancements for ESDoc are pertinent?

Essentially ESDoc can be updated to potentially support anything that can be parsed by Babylon. Also, no promises as I don't control the ESDoc project as a single maintainer from Japan does, but I'd like to see it support at least inline typing compatible with Flow (and presumably TypeScript) via Babylon.

[connor4312]

Automatic detection of inline types as well as the ability to generate typings from interfaces would be huge. Right now we have TypeScript interfaces and separate docblocks for each of them. Also, the ability to use sourcemaps for those "source" links would be fantastic.

Those are my biggest asks from a functional standpoint 😄

[typhonrt]

Well after more perusal seemingly there is going to be an impasse. Given the move to Babylon ESDoc will be able to support flow typing. I have tried many TS samples in ASTExplorer against the flow support; interface example. There is a large overlap between Flow vs TS; here is the best overview I've found, but it's not exhaustive. For the time being given the TS compiler output not being overly flexible with a public plugin API there is no way to strip non-flow compatible output; IE it would be great to target ES6+, but leave in inline types for declarations + interfaces; stripping the rest of non-compatible features. From reading various Github issues there likely will not be any TS support in Babel / Babylon anytime soon.

So, I am aiming to add flow typing to ESDoc soon (in my fork first) which gets things from a documentation output perspective essentially on par with TS minus a few conventions (enum, implements, readonly). I can also take a look at the sourcemaps feature as that is relatively low hanging fruit. Another possibility is providing an alternate runtime for ESDoc using the TS compiler / AST. The architecture of ESDoc is good, but could be modularized with drop in replacements for parsing alternate AST syntax while largely sharing the publication features. BTW I could not find an AST spec for TS like Babylon. From various Github issues on the TS repo often "read the source code" comes up as an answer which is not very helpful. Is there an AST spec I'm missing?

My hands are tied though as the maintainer of ESDoc is largely absent with little communication. He said he'd accept collaborators after v1.0, but progress constantly stalls for months at a time when I could push out v1.0 as specified in a week. I do have a solid grasp on the whole ESDoc codebase, but am not enthused in doing a permanent fork due to visibility issues. I already have a major rewrite of escomplex / typhonjs-escomplex which has my hands full for another month or so which also will have visibility issues in promotion / uptake despite it being a superior solution supporting ES6+ as the old version is now being abandoned by previous maintainers. I am definitely on the fence though for permanently forking ESDoc and likely will if the maintainer hasn't released v1.0 and subsequently allowing actual collaborators by the end of the year.

Anyway this has been a helpful discussion and gives some insight into important documentation features to potentially support in ESDoc. Thanks.

[dandv]

My hands are tied though as the maintainer of ESDoc is largely absent with little communication

Given that my impression of ESDoc may be shared by many others who refrained from commenting, I would support a fork.

[connor4312]

@typhonrt that would be awesome! Long term it'd be great to see a popular fork of ESDoc that could eventually merge back into the main project and bring some organizational changes (like io.js did with Node). I would love to help out, though my free time (that I want to spend at the keyboard) is limited and this project takes up most of it 😄

Regarding Typescript, they have a page on their wiki which gives an example of a linting script. There are also other projects like tslint which use AST parsing. You could also look at the some anemic typedoc project for some inspiration and examples.

[typhonrt]

Well thanks @dandv & @connor4312 for the general support. My guess about the situation is that the ESDoc maintainer is a capable starter / initial architect, but scratched his itch and let things ride. Certainly no problems with that, but then the project got some legs / filled an actual need for many others. I really don't like unnecessary forking and this situation is completely different from what led me to fork escomplex; subsequently a couple of months ago that fellow abandoned escomplex without doing anything during a year of "stewardship", so definitely the right thing there. All this does inform on how to build a community and when you get another contributor who falls in that "1%" you definitely want to get them on board as a collaborator and even the top "5%" due to the relative reversible situation of any bad commit; re: some of Peter Hintjens (RIP) writings on building a community. Which is also captured in the node-influx opening statement, "Interested in becoming a maintainer? Please help out with issues and pull-requests and open an issue introducing yourself! After we've seen you're involved with the project, we'll add you up 👍".

Re: TypeScript I have indeed come across the wiki page mentioned. At least things are contained in types.ts, but is a bit unwieldy still compared to a spec document specific for the AST syntax.

I'll likely be finishing typhonjs-escomplex see where things are at with ESDoc at the end of the year and as mentioned if v1.0 is not pushed out by then and / or I'm not accepted as a collaborator a permanent fork is pertinent (technically it probably should be regardless with what I have in mind). With what I'm pulling off with TyphonJS solid and automatically updated documentation is important. I'm angling to get out a complementary CI tool which on commit of a repo generates docs and uploads them to a server / commit to a specific doc repo for a larger one or many-organization effort.

I'm certainly not against supporting TypeScript for typhonjs-escomplex and likely typhonjs-esdoc. At least with typhonjs-escomplex I have in depth experience with supporting acorn, espree, esprima and babylon generated AST, so uh what could be the difficulty with adding TS... ;) It would be great if things do move in that direction and a TS enabled version of ESDoc fits for influx for some help on getting out the word to the rest of the TypeScript community. I'll drop back by and post an issue if / when this occurs.

[typhonrt]

Just a little heads up.. I am going to start a permanent major fork / rearchitecture of ESDoc in the coming month or so as things eventually fell apart / see end of thread / patience exhausted (https://github.com/esdoc/esdoc/issues/345)... I don't think things will merge back with ESDoc as things go. I can't exactly predict when Typescript support will be added, but I'd like things moving in that direction in Q2 '17 with initial Flow support to sketch out how documentation generation output may be facilitated for TypeScript as well. Quite likely I'll be renaming this effort to aid in visibility / traction, so I'll drop another note here or post a new issue when things approach release candidate / ready to be tested for a significant outside TypeScript project before final release of this functionality as I can use some help from a few knowledgable TypeScript users / developers to fine tune things and get the word out. Alright, have a good and safe weekend folks and chat next year!