Create documentation ?
darkyen opened this issue · 4 comments
I intend to use this library for my custom pure javascript http library which works on cordova and chrome apps runtime. It would be nice to have documentation for the library.
The idea is that this is API-compatible with Node's native http parser, and the way this library is used changes as often as the way their API changes (roughly every other major Node release, though we maintain backwards-compatability to the APIs of older versions of Node for now). If you can convince someone over there to document the main Node http_parser API, that documentation would also apply to this library, but it's technically an internal only API and not worth documenting on their side.
That being said, having a little auxiliary documentation with some example of how to use this stand-alone might be interesting (though not the primary goal of this library), so if anyone wants to contribute some, it would certainly be welcomed.
I will start documenting as I use it in my code. But "changes with every major node release" is rather scary. Can you suggest any other stabler http parsers ?
It will stay backwards-compatible, as people are still using this as far back as node 0.10, and it doesn't change much, but since it is a drop-in replacement for Node's own internal parser, by definition, it must be changed to match whatever their internal API uses.
Looking through our commits, the change for Node 5.x was trivial, just adding some additional supported methods. The change for Node 4.x was more significant internally, mostly because of the changes to keep the 0.12 API working, but it was still only a couple dozen lines. So, I may have overstated how much the API changes.
As far as I know, there are no other pure-JS HTTP parsers (but I haven't looked in a year or so), as, for most cases, Node and the browser themselves handle that layer of communication entirely =).
Makes sense, and I searched for them over the entire internet mostly the ones are tightly coupled to a library or so. I guess I will use this for now :-), and browsers won't let me host a server :D (as I mentioned this is mostly going to run in chrome apps runtime). Closing it now.