Taxi.py: Improve inline documentation
diff --git a/gym/envs/toy_text/taxi.py b/gym/envs/toy_text/taxi.py
index 425892c7734..7aa888ac706 100644
--- a/gym/envs/toy_text/taxi.py
+++ b/gym/envs/toy_text/taxi.py
@@ -15,6 +15,7 @@
     "+---------+",
 ]
 
+
 class TaxiEnv(discrete.DiscreteEnv):
     """
     The Taxi Problem
@@ -45,74 +46,88 @@ class TaxiEnv(discrete.DiscreteEnv):
     - magenta: destination
     - yellow: empty taxi
     - green: full taxi
-    - other letters: locations
-
+    - other letters (R, G, B and Y): locations for passengers and destinations
+
+    actions:
+    - 0: south
+    - 1: north
+    - 2: east
+    - 3: west
+    - 4: pickup
+    - 5: dropoff
+
+    state space is represented by:
+        (taxi_row, taxi_col, passenger_location, destination)
     """
     metadata = {'render.modes': ['human', 'ansi']}
 
     def __init__(self):
-        self.desc = np.asarray(MAP,dtype='c')
+        self.desc = np.asarray(MAP, dtype='c')
 
         self.locs = locs = [(0,0), (0,4), (4,0), (4,3)]
 
-        nS = 500
-        nR = 5
-        nC = 5
-        maxR = nR-1
-        maxC = nC-1
-        isd = np.zeros(nS)
-        nA = 6
-        P = {s : {a : [] for a in range(nA)} for s in range(nS)}
-        for row in range(5):
-            for col in range(5):
-                for passidx in range(5):
-                    for destidx in range(4):
-                        state = self.encode(row, col, passidx, destidx)
-                        if passidx < 4 and passidx != destidx:
-                            isd[state] += 1
-                        for a in range(nA):
+        num_states = 500
+        num_rows = 5
+        num_columns = 5
+        max_row = num_rows - 1
+        max_col = num_columns - 1
+        initial_state_distrib = np.zeros(num_states)
+        num_actions = 6
+        P = {state: {action: []
+                     for action in range(num_actions)} for state in range(num_states)}
+        for row in range(num_rows):
+            for col in range(num_columns):
+                for pass_idx in range(len(locs) + 1):  # +1 for being inside taxi
+                    for dest_idx in range(len(locs)):
+                        state = self.encode(row, col, pass_idx, dest_idx)
+                        if pass_idx < 4 and pass_idx != dest_idx:
+                            initial_state_distrib[state] += 1
+                        for action in range(num_actions):
                             # defaults
-                            newrow, newcol, newpassidx = row, col, passidx
-                            reward = -1
+                            new_row, new_col, new_pass_idx = row, col, pass_idx
+                            reward = -1 # default reward when there is no pickup/dropoff
                             done = False
-                            taxiloc = (row, col)
-
-                            if a==0:
-                                newrow = min(row+1, maxR)
-                            elif a==1:
-                                newrow = max(row-1, 0)
-                            if a==2 and self.desc[1+row,2*col+2]==b":":
-                                newcol = min(col+1, maxC)
-                            elif a==3 and self.desc[1+row,2*col]==b":":
-                                newcol = max(col-1, 0)
-                            elif a==4: # pickup
-                                if (passidx < 4 and taxiloc == locs[passidx]):
-                                    newpassidx = 4
-                                else:
+                            taxi_loc = (row, col)
+
+                            if action == 0:
+                                new_row = min(row + 1, max_row)
+                            elif action == 1:
+                                new_row = max(row - 1, 0)
+                            if action == 2 and self.desc[1 + row, 2 * col + 2] == b":":
+                                new_col = min(col + 1, max_col)
+                            elif action == 3 and self.desc[1 + row, 2 * col] == b":":
+                                new_col = max(col - 1, 0)
+                            elif action == 4:  # pickup
+                                if (pass_idx < 4 and taxi_loc == locs[pass_idx]):
+                                    new_pass_idx = 4
+                                else: # passenger not at location
                                     reward = -10
-                            elif a==5: # dropoff
-                                if (taxiloc == locs[destidx]) and passidx==4:
-                                    newpassidx = destidx
+                            elif action == 5:  # dropoff
+                                if (taxi_loc == locs[dest_idx]) and pass_idx == 4:
+                                    new_pass_idx = dest_idx
                                     done = True
                                     reward = 20
-                                elif (taxiloc in locs) and passidx==4:
-                                    newpassidx = locs.index(taxiloc)
-                                else:
+                                elif (taxi_loc in locs) and pass_idx == 4:
+                                    new_pass_idx = locs.index(taxi_loc)
+                                else: # dropoff at wrong location
                                     reward = -10
-                            newstate = self.encode(newrow, newcol, newpassidx, destidx)
-                            P[state][a].append((1.0, newstate, reward, done))
-        isd /= isd.sum()
-        discrete.DiscreteEnv.__init__(self, nS, nA, P, isd)
-
-    def encode(self, taxirow, taxicol, passloc, destidx):
+                            new_state = self.encode(
+                                new_row, new_col, new_pass_idx, dest_idx)
+                            P[state][action].append(
+                                (1.0, new_state, reward, done))
+        initial_state_distrib /= initial_state_distrib.sum()
+        discrete.DiscreteEnv.__init__(
+            self, num_states, num_actions, P, initial_state_distrib)
+
+    def encode(self, taxi_row, taxi_col, pass_loc, dest_idx):
         # (5) 5, 5, 4
-        i = taxirow
+        i = taxi_row
         i *= 5
-        i += taxicol
+        i += taxi_col
         i *= 5
-        i += passloc
+        i += pass_loc
         i *= 4
-        i += destidx
+        i += dest_idx
         return i
 
     def decode(self, i):
@@ -132,18 +147,21 @@ def render(self, mode='human'):
 
         out = self.desc.copy().tolist()
         out = [[c.decode('utf-8') for c in line] for line in out]
-        taxirow, taxicol, passidx, destidx = self.decode(self.s)
+        taxi_row, taxi_col, pass_idx, dest_idx = self.decode(self.s)
+
         def ul(x): return "_" if x == " " else x
-        if passidx < 4:
-            out[1+taxirow][2*taxicol+1] = utils.colorize(out[1+taxirow][2*taxicol+1], 'yellow', highlight=True)
-            pi, pj = self.locs[passidx]
-            out[1+pi][2*pj+1] = utils.colorize(out[1+pi][2*pj+1], 'blue', bold=True)
-        else: # passenger in taxi
-            out[1+taxirow][2*taxicol+1] = utils.colorize(ul(out[1+taxirow][2*taxicol+1]), 'green', highlight=True)
-
-        di, dj = self.locs[destidx]
-        out[1+di][2*dj+1] = utils.colorize(out[1+di][2*dj+1], 'magenta')
-        outfile.write("\n".join(["".join(row) for row in out])+"\n")
+        if pass_idx < 4:
+            out[1 + taxi_row][2 * taxi_col + 1] = utils.colorize(
+                out[1 + taxi_row][2 * taxi_col + 1], 'yellow', highlight=True)
+            pi, pj = self.locs[pass_idx]
+            out[1 + pi][2 * pj + 1] = utils.colorize(out[1 + pi][2 * pj + 1], 'blue', bold=True)
+        else:  # passenger in taxi
+            out[1 + taxi_row][2 * taxi_col + 1] = utils.colorize(
+                ul(out[1 + taxi_row][2 * taxi_col + 1]), 'green', highlight=True)
+
+        di, dj = self.locs[dest_idx]
+        out[1 + di][2 * dj + 1] = utils.colorize(out[1 + di][2 * dj + 1], 'magenta')
+        outfile.write("\n".join(["".join(row) for row in out]) + "\n")
         if self.lastaction is not None:
             outfile.write("  ({})\n".format(["South", "North", "East", "West", "Pickup", "Dropoff"][self.lastaction]))
         else: outfile.write("\n")

* Use more descriptive variable names
* Fix formatting as per PEP8
* Add some inline documentation for better undrstanding