Added comments

README.md

@@ -1,11 +1,40 @@
+# tensorlm
 
-example_wrappers.py charlm
-Epoch: 1, Step: 100, Avg. Train Loss: 4.477590560913086
-2017-08-21 23:12:12.203845: I tensorflow/core/common_runtime/gpu/pool_allocator.cc:247] PoolAllocator: After 55341 get requests, put_count=55392 evicted_count=1000 eviction_rate=0.0180531 and unsatisfied allocation rate=0.0182143
-2017-08-21 23:12:12.203869: I tensorflow/core/common_runtime/gpu/pool_allocator.cc:259] Raising pool_size_limit_ from 655 to 720
-Epoch: 1, Step: 200, Avg. Train Loss: 3.0998141765594482
-Epoch: 1, Step: 300, Avg. Train Loss: 2.977341890335083
-Epoch: 1, Step: 400, Avg. Train Loss: 2.8836493492126465
-Epoch: 1, Step: 500, Avg. Train Loss: 2.775566816329956
-The e e e e e e e e e e e e e e e e e ee ee ee ee ee e e e e e e e e e e e e ee ee ee ee ee e e e e e e e
-Validation loss: 2.832617928072349
+Generate Shakespeare poems with 4 lines of code.
+
+## Installation
+
+    pip install tensorflow
+    pip install tensorlm
+
+## Usage
+
+    import tensorflow as tf
+    from tensorlm import WordLM
+        
+    with tf.Session() as session:
+        
+        # Create a new model
+        model = CharLM(session, "datasets/sherlock/train.txt", max_vocab_size=96,
+                       neurons_per_layer=100, num_layers=3, num_timesteps=15)
+        
+        # Train it 
+        model.train(session, max_epochs=5, max_steps=500, print_logs=True)
+
+        
+        # Let it generate a text
+        generated = model.sample(session, "The ", num_steps=100)
+        print("The " + generated)
+
+This will output:
+
+    Epoch: 1, Step: 100, Avg. Train Loss: 4.477590560913086
+    Epoch: 1, Step: 200, Avg. Train Loss: 3.0998141765594482
+    Epoch: 1, Step: 300, Avg. Train Loss: 2.977341890335083
+    Epoch: 1, Step: 400, Avg. Train Loss: 2.8836493492126465
+    Epoch: 1, Step: 500, Avg. Train Loss: 2.775566816329956
+    The e e e e e e e e e e e e e e e e e ee ee ee ee ee e e e e e e e e e e e e ee ee ee ee ee e e e e e e e
+
+## Requirements
+
+    tensorflow >= 1.0

examples/example_wrappers.py

@@ -11,7 +11,7 @@
                 evaluate_interval=1000, evaluate_text_path="datasets/sherlock/valid.txt",
                 sample_interval=1000, save_interval_hours=0.5)
 
-    generated = model.sample(session, "The ")
+    generated = model.sample(session, "The ", num_steps=100)
     print("The " + generated)
 
     dev_loss = model.evaluate(session, "datasets/sherlock/valid.txt")

tensorlm/model.py

@@ -43,18 +43,18 @@ class GeneratingLSTM:
 
     Use tensorlm.dataset.Vocabulary for translating the ids to tokens.
 
+    To prevent the model from forgetting its memory state between train_steps, we store the LSTM's
+    cell and hidden state. So, you can feed a long text chunk by chunk into the model and it updates
+    its state after each feed. You can reset the LSTM's cell and hidden state by calling
+    reset_state().
+
     For training and evaluation you can use varying batch sizes and number of time steps, even
     between function calls to train_step(). The number of time steps denotes the number of steps
     that the LSTM is unrolled for. See tf.nn.dynamic_rnn for more info. The batch size and number of
     time steps are determined dynamically based on the input size.
 
     For training, RMSProp is used.
 
-    To prevent the model from forgetting its memory state between train_steps, we store the LSTM's
-    cell and hidden state. So, you can feed a long text chunk by chunk into the model and it updates
-    its state after each feed. You can reset the LSTM's cell and hidden state by calling
-    reset_state().
-
     For saving / reloading the model to / from the filesystem, use the self.saver member of the
     instance. This will be a tf.train.Saver. See the TensorFlow documentation for info about how to
     use the tf.train.Saver. The LSTM's cell and hidden state won't be saved in the output file. Only
@@ -239,25 +239,30 @@ def _build_graph(self, forward_only):
         """Builds the whole computational graph for the LSTM.
 
         Args:
-            forward_only: If True, the graph will also contain back-propagation operations for
-                improving the model's trainable parameters.
+            forward_only (bool): If True, the graph will also contain back-propagation operations
+                for improving the model's trainable parameters.
         """
 
-        # Build the central LSTM
-        def layer():
-            # See https://stackoverflow.com/a/44882273/2628369 for why this local function is
-            # necessary
-            cell = tf.contrib.rnn.LSTMCell(self.neurons_per_layer)
-            cell = tf.contrib.rnn.DropoutWrapper(cell, output_keep_prob=self._output_keep_var)
-            return cell
-
-        self._cell = tf.contrib.rnn.MultiRNNCell([layer() for _ in range(self.num_layers)])
+        self._cell = tf.contrib.rnn.MultiRNNCell(
+            [self._build_lstm_layer() for _ in range(self.num_layers)])
         self._logits = self._build_prediction()
         self._loss = self._build_loss()
 
         if not forward_only:
             self._optimize = self._build_optimizer()
 
+    def _build_lstm_layer(self):
+        """Returns a dropout-wrapped LSTM-cell.
+
+        See https://stackoverflow.com/a/44882273/2628369 for why this local function is necessary.
+
+        Returns:
+            tf.contrib.rnn.DropoutWrapper: The dropout-wrapped LSTM cell.
+        """
+        cell = tf.contrib.rnn.LSTMCell(self.neurons_per_layer)
+        cell = tf.contrib.rnn.DropoutWrapper(cell, output_keep_prob=self._output_keep_var)
+        return cell
+
     def _build_prediction(self):
         """Builds the forward-propagation part of the computational graph.