Current documentation and JavaDoc are far from being perfect

This is not a bug. It is a serious problem that I think many people have with the package. I have no problem with the API, it is very nice, well-structured and extensible, it is fast and robust.

But it is, quite frankly, horribly documented.

It took me several DAYS (no kidding) of experimentation, sifting through piles of one-sentence JavaDoc (which isn't clearly referenced on the README btw) and reading a bunch of source code to grasp a basic understanding of how Takes works, how one controls and customizes different parts of the data and event flow, what the basic subclasses do and how their constructors work.

NOW I understand enough to do decently fast development with Takes. But I doubt that everyone has the time to spare or the willpower to dissect a library just to be able to use it. I, at several points, was just hunting down bugs I introduced because I did not know that Takes behaved in a certain way. In a way that was not documented. I was looking to add a certain feature and needed several attempts of using different decorators until I found the one that did the thing I wanted it to do.

Takes is a great library, don't get me wrong. But great libraries deserve great documentation. Therefore, I suggest we concentrate our efforts on the following:

1. Document behavior that is not obvious. Some examples of undocumented behavior I encountered:

• Most response decorators that add a body also add a Content-Length header. It is up for debate whether that is a good thing or not, but this behavior had me debugging about three hours until I figured I needed to remove a wrong Content-Length header silently set by a RsText decorator.
• Document how different Backs handle Socket closing and opening and whether they respond to Connection: keep-alive headers. I still do not know how this works and commonly get 29s TTFB because some socket is still open, timing out or whatever. Somebody has to know how this all works.
• Gzip may cause extreme lag and even crashes when a Take throws an exception that should be handled by a Fallback. Explain how to properly use the Gzip decorator and where it should be avoided.

2. For every class and major method, document common use cases and workflows, example use cases and gotchas like the ones described above. Describe in more detail how the classes and methods behave, how they perform and known edge cases that might occur.

3. Likewise, for every constructor, document how it behaves differently than the others, in which situation it may be preferred over other constructors, etc.

4. Create a more comprehensive explanation of how the Takes API and architecture works and how one goes about extending it in various ways. Explain what to do and what not to do when extending the framework and when compositing its parts.

I know that most of the things listed under undocumented behavior may be my fault at least partially. But it always took a long time for me to find out what I did wrong and exactly why, in the end, it really always was a feature and not a bug, just an undocumented feature.

If there is no real comprehensive API documentation apart from the JavaDoc, then the JavaDoc should also contain all necessary information.

Thanks to all the engaged people on this great project!