High-level description of how this framework works

[nalzok]

Hi there!

I found this framework interesting and promising due to its handy API syntax. However, the documentation somewhat confuses me. Well, this is unsurprising because I'm not an expert in Web development anyway. Actually, I have received little formal education in CS, but I know the very basics of TCP thanks to Beej's Guide to Network Programming. In addition, I have previously worked with kcgi, Flask, and Django.

Anyway, from my perspective, both the comments in the header files and the HTML document are enumerating functions without sufficiently stating how they interact with each other as a whole. For example, the HTML document begins with introducing fio_protocol_s which has a lot of on_* callbacks. This part inevitably contains several forward references to stuff like FIO_PR_LOCK_TASK. When working through it I'm totally lost for a while, because I have no idea how the connections and locks are handled by the framework (without reading the rest of the document, which is kinda long and dry).

Personally, I would like to see a high-level description at the very beginning of this documentation, preferably presented with a diagram like the following one. Plain text descriptions like "On startup, we allocate a fio_protocol_s object with malloc and set its callback functions by writing a compound literal. Next, we get a UUID from somewhere. Then we can conveniently attach it to a connection with fio_attach and set up some kind of lock. ..." are also nice to have.

[boazsegev]

@sunqingyao ,

Thank you for opening this issue. I was looking at the documentation and you are right, it's missing an overview of the library.

The HTML documentation source code is at docs/_SOURCE and I will try to add an overview to that location when I can.

Right now, the example code should provide the best overview, and I hope I will be able to improve the documentation soon.

I will keep this issue open until I update the documentation.

[nalzok]

Thanks!

The example code in the repository is great and informative, but unfortunately those in the HTML document are not. Please update them as well. For example, the echo server example doesn't even compile with facil.io 7.0.0.