From 06bdc2860c6809ed8a0910ae888863d540fba885 Mon Sep 17 00:00:00 2001
From: Peter Zhokhov <peterz@openai.com>
Date: Tue, 11 Sep 2018 12:40:23 -0700
Subject: [PATCH] docstrings about vecenvs

---
 baselines/common/vec_env/__init__.py        |  5 ++++-
 baselines/common/vec_env/dummy_vec_env.py   | 11 +++++++++++
 baselines/common/vec_env/shmem_vec_env.py   |  3 +--
 baselines/common/vec_env/subproc_vec_env.py |  8 +++++++-
 4 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/baselines/common/vec_env/__init__.py b/baselines/common/vec_env/__init__.py
index 37bc78e..5aee01e 100644
--- a/baselines/common/vec_env/__init__.py
+++ b/baselines/common/vec_env/__init__.py
@@ -25,7 +25,10 @@ class NotSteppingError(Exception):
 
 class VecEnv(ABC):
     """
-    An abstract asynchronous, vectorized environment.
+    An abstract asynchronous, vectorized environment. 
+    Used to batch data from multiple copies of an environment, so that
+    each observation becomes an batch of observations, and expected action is a batch of actions to 
+    be applied per-environment.
     """
 
     def __init__(self, num_envs, observation_space, action_space):
diff --git a/baselines/common/vec_env/dummy_vec_env.py b/baselines/common/vec_env/dummy_vec_env.py
index 9c3858e..e1983bd 100644
--- a/baselines/common/vec_env/dummy_vec_env.py
+++ b/baselines/common/vec_env/dummy_vec_env.py
@@ -4,7 +4,18 @@ from . import VecEnv
 from .util import copy_obs_dict, dict_to_obs, obs_space_info
 
 class DummyVecEnv(VecEnv):
+    """
+    VecEnv that does runs multiple environments sequentially, that is,
+    the step and reset commands are send to one environment at a time.
+    Useful when debugging and when num_env == 1 (in the latter case, 
+    avoids communication overhead)
+    """
     def __init__(self, env_fns):
+        """
+        Arguments:
+    
+        env_fns: iterable of callables      functions that build environments   
+        """
         self.envs = [fn() for fn in env_fns]
         env = self.envs[0]
         VecEnv.__init__(self, len(env_fns), env.observation_space, env.action_space)
diff --git a/baselines/common/vec_env/shmem_vec_env.py b/baselines/common/vec_env/shmem_vec_env.py
index b2c8e16..fcdcf47 100644
--- a/baselines/common/vec_env/shmem_vec_env.py
+++ b/baselines/common/vec_env/shmem_vec_env.py
@@ -19,8 +19,7 @@ _NP_TO_CT = {np.float32: ctypes.c_float,
 
 class ShmemVecEnv(VecEnv):
     """
-    An AsyncEnv that uses multiprocessing to run multiple
-    environments in parallel.
+    Optimized version of SubprocVecEnv that uses shared variables to communicate observations.
     """
 
     def __init__(self, env_fns, spaces=None):
diff --git a/baselines/common/vec_env/subproc_vec_env.py b/baselines/common/vec_env/subproc_vec_env.py
index 83192cb..addc902 100644
--- a/baselines/common/vec_env/subproc_vec_env.py
+++ b/baselines/common/vec_env/subproc_vec_env.py
@@ -32,9 +32,15 @@ def worker(remote, parent_remote, env_fn_wrapper):
 
 
 class SubprocVecEnv(VecEnv):
+    """
+    VecEnv that runs multiple environments in parallel in subproceses and communicates with them via pipes. 
+    Recommended to use when num_envs > 1 and step() can be a bottleneck. 
+    """
     def __init__(self, env_fns, spaces=None):
         """
-        envs: list of gym environments to run in subprocesses
+        Arguments:
+
+        env_fns: iterable of callables -  functions that create environments to run in subprocesses. Need to be cloud-pickleable
         """
         self.waiting = False
         nenvs = len(env_fns)