Improving docstrings and comments in train profiler, objectives, etc

Author: jindrahelcl

neuralmonkey/attention/combination.py

@@ -180,11 +180,14 @@ def masks_concat(self) -> tf.Tensor:
 
     def initial_loop_state(self) -> AttentionLoopState:
 
+        # Similarly to the feed_forward attention, we need to build the encoder
+        # projections and masks before the while loop is entered so they are
+        # not created as a part of the loop
+
         # pylint: disable=not-an-iterable
-        # TODO blessing
         for val in self.encoder_projections_for_logits:
-            debug(val)
-        debug(self.masks_concat)
+            debug(val, "bless")
+        debug(self.masks_concat, "bless")
 
         length = sum(tf.shape(s)[1] for s in self._encoders_tensors)
         # pylint: enable=not-an-iterable
@@ -195,7 +198,7 @@ def initial_loop_state(self) -> AttentionLoopState:
         return empty_attention_loop_state(self.batch_size, length,
                                           self.context_vector_size)
 
-    def get_encoder_projections(self, scope) -> List[tf.Tensor]:
+    def get_encoder_projections(self, scope: str) -> List[tf.Tensor]:
         encoder_projections = []
         with tf.variable_scope(scope):
             for i, encoder_tensor in enumerate(self._encoders_tensors):

neuralmonkey/trainers/objective.py

@@ -14,59 +14,81 @@
 
 
 class Objective(Generic[MP]):
-    """The training objective.
-
-    Attributes:
-        name: The name for the objective. Used in TensorBoard.
-        decoder: The decoder which generates the value to optimize.
-        loss: The loss tensor fetched by the trainer.
-        gradients: Manually specified gradients. Useful for reinforcement
-            learning.
-        weight: The weight of this objective. The loss will be multiplied by
-            this so the gradients can be controled in case of multiple
-            objectives.
-    """
+    """The training objective base class."""
 
     def __init__(self, name: str, decoder: MP) -> None:
+        """Construct the objective.
+
+        Arguments:
+            name: The name for the objective. This will be used e.g. in
+                TensorBoard.
+        """
         self._name = name
         self._decoder = decoder
 
     @property
     def decoder(self) -> MP:
+        """Get the decoder used by the objective."""
         return self._decoder
 
     @property
     def name(self) -> str:
+        """Get the name of the objective."""
         return self._name
 
     @abstractproperty
     def loss(self) -> tf.Tensor:
+        """Return the loss tensor fetched by the trainer."""
         raise NotImplementedError()
 
     @property
     def gradients(self) -> Optional[Gradients]:
+        """Manually specified gradients - useful for reinforcement learning."""
         return None
 
     @property
     def weight(self) -> Optional[tf.Tensor]:
+        """Return the weight of this objective.
+
+        The loss will be multiplied by this so the gradients can be controlled
+        in case of multiple objectives.
+
+        Returns:
+            An optional tensor. If None, default weight of 1 is assumed.
+        """
         return None
 
 
 class CostObjective(Objective[GenericModelPart]):
+    """Cost objective class.
+
+    This class represent objectives that are based directly on a `cost`
+    attribute of any compatible model part.
+    """
 
     def __init__(self, decoder: GenericModelPart,
                  weight: ObjectiveWeight = None) -> None:
+        """Construct a new instance of the `CostObjective` class.
+
+        Arguments:
+            decoder: A `GenericModelPart` instance that has a `cost` attribute.
+            weight: The weight of the objective.
+
+        Raises:
+            `TypeError` when the decoder argument does not have the `cost`
+            attribute.
+        """
         check_argument_types()
+        if "cost" not in dir(decoder):
+            raise TypeError("The decoder does not have the 'cost' attribute")
 
         name = "{} - cost".format(str(decoder))
+
         Objective[GenericModelPart].__init__(self, name, decoder)
         self._weight = weight
 
     @tensor
     def loss(self) -> tf.Tensor:
-        if "cost" not in dir(self.decoder):
-            raise TypeError("The decoder does not have the 'cost' attribute")
-
         return getattr(self.decoder, "cost")
 
     @tensor

neuralmonkey/training_profiler.py

@@ -7,6 +7,17 @@
 
 
 class TrainingProfiler:
+    """Training profiler class.
+
+    This class is used for measuring inter-validation and validation times
+    during training. It stores the training profile in the `inter_val_times`
+    and `validation_times` lists. These can be accessed by the toolkit to
+    provide the user with insight about the training and validation time ratio.
+
+    Additionally, this class provides getters for last logging and validation
+    times, which can be used for deciding whether to log training progress
+    or validate the model.
+    """
 
     def __init__(self) -> None:
         self._start_time = None  # type: Optional[float]