From 4c81e731a485d3ea84049ef6d568153c8b10e90b Mon Sep 17 00:00:00 2001
From: jvoisin
Date: Sun, 27 Oct 2013 23:01:20 +0000
Subject: Improves documentation

---
 MAT/images.py | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

(limited to 'MAT/images.py')

diff --git a/MAT/images.py b/MAT/images.py
index 55c1a90..dc96e6a 100644
--- a/MAT/images.py
+++ b/MAT/images.py
@@ -1,41 +1,52 @@
-'''
-    Takes care about pictures formats
+''' Takes care about pictures formats
+
+References:
+    - JFIF: http://www.ecma-international.org/publications/techreports/E-TR-098.htm
+    - PNG: http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/PNG.html
+    - PNG: http://www.w3.org/TR/PNG-Chunks.html
 '''
 
 import parser
 
 
 class JpegStripper(parser.GenericParser):
-    '''
-        represents a jpeg file
+    ''' Represents a jpeg file.
+        Custom Huffman and Quantization tables
+        are stripped: they may leak
+        some info, and the quality loss is minor.
     '''
     def _should_remove(self, field):
+        ''' Return True if the field is compromising
         '''
-            return True if the field is compromising
-        '''
-        field_list = frozenset(['start_image', 'app0', 'start_frame',
-                'start_scan', 'data', 'end_image'])
+        field_list = frozenset([
+            'start_image',  # start of the image
+            'app0',         # JFIF data
+            'start_frame',  # specify width, height, number of components
+            'start_scan',   # specify which slice of data the top-to-bottom scan contains
+            'data',         # actual data
+            'end_image'])   # end of the image
         if field.name in field_list:
             return False
-        elif field.name.startswith('quantization['):
+        elif field.name.startswith('quantization['):  # custom Quant. tables
             return False
-        elif field.name.startswith('huffman['):
+        elif field.name.startswith('huffman['):  # custom Huffman tables
             return False
         return True
 
 
 class PngStripper(parser.GenericParser):
-    '''
-        represents a png file
-        see : http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/PNG.html
+    ''' Represents a png file
     '''
     def _should_remove(self, field):
+        ''' Return True if the field is compromising
         '''
-            return True if the field is compromising
-        '''
-        field_list = frozenset(['id', 'header', 'physical', 'end'])
+        field_list = frozenset([
+            'id',
+            'header',   # PNG header
+            'physical', # the intended pixel size or aspect ratio
+            'end'])     # end of the image
         if field.name in field_list:
             return False
-        if field.name.startswith('data['):
+        if field.name.startswith('data['):  # data
             return False
         return True
-- 
cgit v1.3