update docs on augmentor

docs/tutorial/extend/augmentor.md

@@ -7,32 +7,38 @@ An augmentor is a part of the DataFlow, so you can always
 to do whatever operations to your data, rather than writing an augmentor.
 Augmentors just sometimes make things easier.
 
-An augmentor maps images to images.
+An image augmentor maps an image to an image.
 If you have such a mapping function `f` already, you can simply use `imgaug.MapImage(f)` as the
 augmentor, or use `MapDataComponent(dataflow, f, index)` as the DataFlow.
 In other words, for simple mapping you do not need to write an augmentor.
 
-An augmentor may do something more than applying a mapping. The interface you will need to implement
-is:
+An augmentor may do something more than just applying a mapping.
+The interface you will need to implement is:
 
 ```python
 class MyAug(imgaug.ImageAugmentor):
-	def _get_augment_params(self, img):
-		# generated random params with self.rng
-	  return params
+  def _get_augment_params(self, img):
+    # generated random params with self.rng
+    return params
 
   def _augment(self, img, params):
-	  return augmented_img
+    return augmented_img
+
+  # optional method
+  def _augment_coords(self, coords, param):
+    # coords is a Nx2 floating point array, each row is (x, y)
+    return augmented_coords
 ```
 
 It does the following extra things for you:
 
 1. `self.rng` is a `np.random.RandomState` object,
-	guaranteed to have different seeds when you use multiprocess prefetch.
-	In multiprocess settings, you have to use this rng to generate random numbers.
-
-2. Random parameter generation and the actual augmentation is separated. This allows you to apply the
-	same transformation to several images together (with `AugmentImageComponents`),
-	which is essential to tasks such as segmentation.
-	Or apply the same transformations to images plus coordinate labels (with `AugmentImageCoordinates`),
-	which is essential to tasks such as detection and localization.
+  guaranteed to have different seeds when you use multiprocess prefetch.
+  In multiprocess settings, you have to use this rng to generate random numbers.
+
+2. The logic of random parameter generation and the actual augmentation is separated in different methods.
+  This allows you to apply the
+  same transformation to several images together (with `AugmentImageComponents`),
+  which is essential to tasks such as segmentation.
+  Or apply the same transformations to images plus coordinate labels (with `AugmentImageCoordinates`),
+  which is essential to tasks such as detection and localization.

tensorpack/callbacks/monitor.py

@@ -198,8 +198,10 @@ def TFSummaryWriter(*args, **kwargs):
 
 class JSONWriter(TrainingMonitor):
     """
-    Write all scalar data to a json, grouped by their global step.
+    Write all scalar data to a json file under ``logger.LOG_DIR``, grouped by their global step.
+    It also tries to recover the epoch number during setup, if an existing json file is found at the same place.
     """
+
     FILENAME = 'stat.json'
 
     def __new__(cls):

tensorpack/dataflow/imgaug/base.py

@@ -63,6 +63,11 @@ class Augmentor(object):
 
 class ImageAugmentor(Augmentor):
     def _augment_coords(self, coords, param):
+        """
+        By default, keeps coordinates unchanged.
+        If a subclass changes coordinates but couldn't implement this method,
+        it should ``raise NotImplementedError()``.
+        """
         return coords