From 88647595ac52b2301b62f2893fbd1b5c94ae3ffb Mon Sep 17 00:00:00 2001
From: Marian Beermann <public@enkore.de>
Date: Fri, 31 Mar 2017 13:39:54 +0200
Subject: [PATCH] compress: docs

---
 src/borg/compress.pyx | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/borg/compress.pyx b/src/borg/compress.pyx
index 2da2389e4..8cd094507 100644
--- a/src/borg/compress.pyx
+++ b/src/borg/compress.pyx
@@ -1,3 +1,28 @@
+"""
+borg.compress
+=============
+
+Compression is applied to chunks after ID hashing (so the ID is a direct function of the
+plain chunk, compression is irrelevant to it), and of course before encryption.
+
+Borg has a flexible scheme for deciding which compression to use for chunks.
+
+First, there is a global default set by the --compression command line option,
+which sets the .compressor attribute on the Key.
+
+For chunks that emanate from files CompressionDecider1 may set a specific
+Compressor based on patterns (this is the --compression-from option). This is stored
+as a Compressor instance in the "compress" key in the Chunk's meta dictionary.
+
+When compressing either the Compressor specified in the Chunk's meta dictionary
+is used, or the default Compressor of the key.
+
+The "auto" mode (e.g. --compression auto,lzma,4) is implemented as a meta Compressor,
+meaning that Auto acts like a Compressor, but defers actual work to others (namely
+LZ4 as a heuristic whether compression is worth it, and the specified Compressor
+for the actual compression).
+"""
+
 import zlib
 from collections import namedtuple