[refactor] Add comments

core/executor.py

@@ -241,8 +241,12 @@ def RunSimpleCommand(self, cmd_val, cmd_st, do_fork, call_procs=True):
       thunk = process.ExternalThunk(self.ext_prog, argv0_path, cmd_val, environ)
       p = process.Process(thunk, self.job_state, self.tracer)
       status = p.RunWait(self.waiter, trace.External(cmd_val.argv))
-      cmd_st.show_code = True  # this is a "leaf" for errors
+
+      # this is close to a "leaf" for errors
+      # problem: permission denied EACCESS prints duplicate messages
       # TODO: add message command 'ls' failed
+      cmd_st.show_code = True
+
       return status
 
     self.tracer.OnExec(cmd_val.argv)

core/process.py

@@ -107,9 +107,10 @@ def __repr__(self):
 
 
 class FdState(object):
-  """This is for the current process, as opposed to child processes.
-
-  For example, you can do 'myfunc > out.txt' without forking.
+  """File descriptor state for the current process.
+  
+  For example, you can do 'myfunc > out.txt' without forking.  Child processes
+  inherit our state.
   """
   def __init__(self, errfmt, job_state, mem, tracer, waiter):
     # type: (ErrorFormatter, JobState, Mem, Optional[dev.Tracer], Optional[Waiter]) -> None
@@ -483,7 +484,6 @@ def MakePermanent(self):
 
 
 class ChildStateChange(object):
-
   def __init__(self):
     # type: () -> None
     """Empty constructor for mycpp."""
@@ -533,6 +533,8 @@ def Apply(self):
 
 
 class ExternalProgram(object):
+  """The capability to execute an external program like 'ls'. """
+
   def __init__(self,
                hijack_shebang,  # type: str
                fd_state,  # type: FdState
@@ -584,9 +586,6 @@ def _Exec(self, argv0_path, argv, argv0_spid, environ, should_retry):
         finally:
           f.close()
 
-    # TODO: If there is an error, like the file isn't executable, then we should
-    # exit, and the parent will reap it.  Should it capture stderr?
-
     try:
       posix.execve(argv0_path, argv, environ)
     except OSError as e:

osh/builtin_comp.py

@@ -170,6 +170,7 @@ def Build(self, argv, arg, base_opts):
         # directory, and external commands in $PATH.
 
         actions.append(_FixedWordsAction(consts.BUILTIN_NAMES))
+        # TODO: Fix bug #1064.  These should be dynamic.
         actions.append(_FixedWordsAction(list(self.parse_ctx.aliases)))
         actions.append(_FixedWordsAction(list(cmd_ev.procs)))
         actions.append(_FixedWordsAction(lexer_def.OSH_KEYWORD_NAMES))