Documentation: Better file formats documentation

1 files changed, 73 insertions, 6 deletions

diff --git a/Base/usr/share/man/man5/ipc.md b/Base/usr/share/man/man5/ipc.md
index 8dd375343a..33163309e5 100644
--- a/Base/usr/share/man/man5/ipc.md
+++ b/Base/usr/share/man/man5/ipc.md
@@ -1,6 +1,6 @@
 ## Name
 
-ipc - Inter Process Communication endpoint definition format
+IPC - Inter-Process Communication endpoint definition format (.ipc)
 
 ## Synopsis
 
@@ -8,10 +8,77 @@ The IPC format of SerenityOS is a domain-specific language (DSL) used to define
 
 ## Description
 
-These files are human-readable, have no easily detectable filemagic, and define IPC interfaces.
-The format is loosely inspired by C++ headers.
+Informally, IPC files - with the help of the IPC compiler - are used to generate message classes that will wrap messages
+for interprocess communication in the system. IPC syntax is loosely inspired by C++ headers. Generated IPC message
+classes support encode and decode functions to pass messages between the processes.
 
-## See Also
+Every IPC pair in the system has a client endpoint and a server endpoint that are described in the IPC files.
+Each IPC endpoint should have a unique hashable name that will uniquely identify endpoints in the system.
 
-- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/).
-- [ipc(4)](help://man/4/ipc) (IPC Unix socket documentation)
+There are 2 types of APIs that are supported by the IPC files: synchronous and asynchronous.
+Synchronous function calls always wait for a response from the other side, while the asynchronous counterparts do not.
+In other words, in case of the synchronous calls, the IPC library will not return until it has a response for a caller.
+
+Ideally, all APIs for the server endpoint should be asynchronous.
+
+## Examples
+
+To create a new connection, you first need to generate client and server endpoints.
+These endpoints should implement the communication logic using the IPC compiler-generated API messages.
+
+Start from defining an endpoint in the IPC file in `MyServer.ipc`.
+
+```
+endpoint MyServer
+{
+    SyncAPI(String text) => (i32 status)
+    AsyncAPI(i32 mode) =|
+}
+```
+
+Part of the generated C++ messages:
+
+```cpp
+class SyncAPI final : public IPC::Message {
+public:
+    using ResponseType = SyncAPIResponse;
+    SyncAPI(const String& text) : m_text(text) {}
+    virtual ~SyncAPI() override {}
+    static OwnPtr<SyncAPI> decode(...);
+    virtual IPC::MessageBuffer encode(...) const override;
+};
+```
+
+Then, you need to inherit your connection class from `IPC::ConnectionFromClient` with created server and client
+endpoints as template parameters if it is a server connection. Otherwise, your class need to be inherited
+from `IPC::ConnectionToServer` with created server and client endpoints as template parameters and from the client
+endpoint class.
+
+Part of the connection implementations:
+
+```cpp
+// Server side.
+namespace MyServer {
+
+class ConnectionFromClient final
+    : public IPC::ConnectionFromClient<MyClientEndpoint, MyServerEndpoint> {};
+
+}
+
+// Client side.
+namespace MyClient {
+    
+    class Client final
+        : public IPC::ConnectionToServer<MyClientEndpoint, MyServerEndpoint>
+        , public MyClientEndpoint {};
+    
+}
+```
+
+Note, there are two types of functions for sending the messages: synchronous and asynchronous. The generated
+asynchronous functions are prefixed with `async_` and the names of the synchronous functions are not changed.
+
+## See also
+
+- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp)
+- [ipc(4)](help://man/4/ipc) (IPC Unix socket documentation)