Feature request: documentation

[mkroman]

This gem desperately lacks documentation of the code. Navigating the code trying to figure out where something is instantiated and used when using it with my own code that's using EventMachine takes a lot of effort. Documenting the code would make this much easier.

I'm creating this feature request to track this effort.

[jcoglan]

Could you be a little more specific about ways in which the documentation is not serving your needs, or what questions it's not answering?

[mkroman]

Sorry for the late reply and the lack of clarification.

I meant to say that the code of the gem lacks documentation. I'm working with some code that tries to clean up servers and gracefully close connections, and it's been difficult navigating this library's code.

[jcoglan]

So for a variety of reasons I tend not to do API documentation -- largely because the library's users won't actually touch most of the methods directly, and because it doesn't do a great job of telling them how to use the library.

As regards your issue, one reason I'd struggle to do this is that I don't know what sorts of questions you have or what about the codebase is confusing -- I'm biased by my familiarity with it. It's possible that other forms of docs would be better for your use, e.g. in the style of the architecture docs here:

https://faye.jcoglan.com/architecture.html

If you give me some of the specific questions you have, I can probably answer them and this would provide useful input for seeing what extra docs we should have.