From d766e0619664a856f88b515d6963ea0d8f611ae4 Mon Sep 17 00:00:00 2001
From: drebs <drebs@leap.se>
Date: Sat, 9 Dec 2017 08:48:53 -0200
Subject: [PATCH] [doc] improve documentation on IBlobsBackend
---
docs/api/blobs-server-backend.rst | 25 ++++++++++++++++++++-----
1 file changed, 20 insertions(+), 5 deletions(-)
diff --git a/docs/api/blobs-server-backend.rst b/docs/api/blobs-server-backend.rst
index 770ac806..7011d66d 100644
--- a/docs/api/blobs-server-backend.rst
+++ b/docs/api/blobs-server-backend.rst
@@ -1,11 +1,26 @@
-Blobs Server-side Data Backend API
-==================================
+Blobs Server-side Backend Interface
+===================================
-Blobs Backend Interface
------------------------
+The :ref:`blobs` functionality has the purpose of adding to Soledad the
+capacity of handling binary objects efficiently. In this case, efficiency means
+low use of resources (memory, cpu, and time) and storage scalability. The
+choice of which data storage backend to use for Blobs affects each of these
+properties in different ways.
+
+The :ref:`blobs-backend-interface` is provided so that Soledad Server is
+agnostic of which data backend is used for Blobs storage. In order to add a new
+backend, one needs to:
+
+* implement a backend according to the :ref:`IBlobsBackend <blobs-backend-interface>` interface,
+* register the new handler in the Twisted-based ``BlobsResource``, and
+* instantiate the Twisted-based ``BlobsResource`` using the new handler.
+
+.. _blobs-backend-interface:
+
+``IBlobsBackend`` Interface
+---------------------------
.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend
:members:
:undoc-members:
- :special-members: __init__
:show-inheritance:
--
GitLab