From eb28d171f3da509d6e0794cb541320e2eb6dbffd Mon Sep 17 00:00:00 2001
From: Christian Kamm <mail@ckamm.de>
Date: Tue, 8 Dec 2015 10:59:42 +0100
Subject: [PATCH] Doc: Add checksum overview

---
 src/libsync/checksums.cpp | 54 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/src/libsync/checksums.cpp b/src/libsync/checksums.cpp
index 80fffafa62..1e4e29539f 100644
--- a/src/libsync/checksums.cpp
+++ b/src/libsync/checksums.cpp
@@ -20,6 +20,60 @@
 
 #include <qtconcurrentrun.h>
 
+/** \file checksums.cpp
+ *
+ * \brief Computing and validating file checksums
+ *
+ * Overview
+ * --------
+ *
+ * Checksums are used in two distinct ways during synchronization:
+ *
+ * - to guard uploads and downloads against data corruption
+ *   (transmission checksum)
+ * - to quickly check whether the content of a file has changed
+ *   to avoid redundant uploads (content checksum)
+ *
+ * In principle both are independent and different checksumming
+ * algorithms can be used. To avoid redundant computations, it can
+ * make sense to use the same checksum algorithm though.
+ *
+ * Transmission Checksums
+ * ----------------------
+ *
+ * The usage of transmission checksums is currently optional and needs
+ * to be explicitly enabled by adding 'transmissionChecksum=TYPE' to
+ * the '[General]' section of the config file.
+ *
+ * When enabled, the checksum will be calculated on upload and sent to
+ * the server in the OC-Checksum header with the format 'TYPE:CHECKSUM'.
+ *
+ * On download, the header with the same name is read and if the
+ * received data does not have the expected checksum, the download is
+ * rejected.
+ *
+ * Transmission checksums guard a specific sync action and are not stored
+ * in the database.
+ *
+ * Content Checksums
+ * -----------------
+ *
+ * Sometimes the metadata of a local file changes while the content stays
+ * unchanged. Content checksums allow the sync client to avoid uploading
+ * the same data again by comparing the file's actual checksum to the
+ * checksum stored in the database.
+ *
+ * Content checksums are not sent to the server.
+ *
+ * Checksum Algorithms
+ * -------------------
+ *
+ * - Adler32 (requires zlib)
+ * - MD5
+ * - SHA1
+ *
+ */
+
 namespace OCC {
 
 QByteArray makeChecksumHeader(const QByteArray& checksumType, const QByteArray& checksum)