Current documentation and JavaDoc are far from being perfect

[kleinesfilmroellchen]

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!

[0crat]

@paulodamaso/z please, pay attention to this issue

[paulodamaso]

@0crat in

[kleinesfilmroellchen]

I have, again, stumbled across a quirk in one class's behavior: RsEmpty adds an HTTP header with a 204 status code. I do not know if most decorators do this, but it again lead to an issue without good error reporting that was fully on my side. I only found out after - again! - looking into the (luckily very simple) source code of said decorator and discovering that behavior. Everything fine with the library, nothing fine with the documentation. The head() iterable of Response includes the RESPONSE LINE of HTTP itself, i.e. HTTP/1.1 200 OK. Please clarify this with Responses documentation.

[paulodamaso]

@0crat status

[0crat]

@0crat status (here)

@paulodamaso This is what I know about this job in C3FFK3YAY, as in §32:

• The job #1041 is in scope for 6days
• The role is DEV
• The job is not assigned to anyone
• The budget is not set yet
• These users are banned and won't be assigned:
  • @kleinesfilmroellchen/z: This user reported the ticket
• Job footprint (restricted area)

[kleinesfilmroellchen]

... and more undocumented behavior: as it seems, non-faked Request objects connect directly to the socket's input stream with their body(). This means that trying to receive all bytes from the body input stream will result in an infinitely blocking method call, as the socket is of course still open for sending the response.

Just in case anyone's wondering, the workaround is to make an InputStream that reads the number of bytes specified in the Content-Length header of the request. Or use some other method of limiting the number of bytes read.

[yegor256]

@kleinesfilmroellchen many thanks for this ticket! Maybe you can help us improve the documentation? A few pull requests will definitely be helpful. In the mean time, I will also try to do some improvements.

[yegor256]

@baudoliver7 maybe you can help too?

[kleinesfilmroellchen]

This issue is two years old. I have since abandoned the project that used takes, I neither use Java nor takes anymore. You can leave this issue open or close it, I don't care, but I'll not be involved anymore.