Refactor DebuggerCommand.

Rename onClient to onClientImpl and move to protected space. Rename onClientD to onClient. Add comments.

hphp/runtime/eval/debugger/cmd/cmd_abort.cpp

@@ -35,8 +35,8 @@ bool CmdAbort::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdAbort::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdAbort::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   if (client->argCount() == 0) {
     client->tutorial(

hphp/runtime/eval/debugger/cmd/cmd_abort.h

@@ -28,7 +28,9 @@ public:
   CmdAbort() : DebuggerCommand(KindOfAbort) {}
 
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 };
 
 ///////////////////////////////////////////////////////////////////////////////

hphp/runtime/eval/debugger/cmd/cmd_break.cpp

@@ -391,8 +391,8 @@ bool CmdBreak::addToBreakpointListAndUpdateServer(
 // Carries out the Break command. This always involves an action on the
 // client and usually, but not always, involves the server by sending
 // this command to the server and waiting for its response.
-bool CmdBreak::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdBreak::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   bool regex = false;
   BreakPointInfo::State state = BreakPointInfo::Always;

hphp/runtime/eval/debugger/cmd/cmd_break.h

@@ -27,18 +27,45 @@ class CmdBreak : public DebuggerCommand {
 public:
   CmdBreak() : DebuggerCommand(KindOfBreak), m_breakpoints(nullptr) {}
 
+  // Informs the client of all strings that may follow a break command.
+  // Used for auto completion. The client uses the prefix of the argument
+  // following the command to narrow down the list displayed to the user.
   virtual void list(DebuggerClient *client);
+
+  // The text to display when the debugger client processes "help break".
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
+  // Updates the client with information about the execution of this command.
+  // This information is not used by the command line client, but can
+  // be accessed via the debugger client API exposed to PHP programs.
   virtual void setClientOutput(DebuggerClient *client);
+
+  // Updates the breakpoint list in the proxy with the new list
+  // received from the client. Then sends the command back to the
+  // client as confirmation. Returns false if the confirmation message
+  // send failed.
   virtual bool onServer(DebuggerProxy *proxy);
 
+  // Creates a new CmdBreak instance, sets its breakpoints to the client's
+  // list, sends the command to the server and waits for a response.
   static bool SendClientBreakpointListToServer(DebuggerClient *client);
 
 protected:
+  // Carries out the Break command. This always involves an action on the
+  // client and usually, but not always, involves the server by sending
+  // this command to the server and waiting for its response.
+  virtual bool onClientImpl(DebuggerClient *client);
+
+  // Serializes this command into the given Thrift buffer.
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
+
+  // Deserializes a CmdBreak from the given Thrift buffer.
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
+
+  // Adds conditional or watch clause to the breakpoint info if needed.
+  // Then adds the breakpoint to client's list and sends this command
+  // to the server so that it too can update it's list.
+  // Returns false if the breakpoint is not well formed.
   bool addToBreakpointListAndUpdateServer(
       DebuggerClient *client, BreakPointInfoPtr bpi, int index);
 
@@ -53,14 +80,37 @@ private:
   // Holds the breakpoint collection of a CmdBreak received via Thrift.
   BreakPointInfoPtrVec m_bps;
 
+  // Uses the client to send this command to the server, which
+  // will update its breakpoint list with the one in this command.
+  // The client will block until the server echoes
+  // this command back to it. The echoed command is discarded.
   bool updateServer(DebuggerClient *client);
+
+  // Carries out the "break list" command.
   bool processList(DebuggerClient *client);
+
+  // Carries out commands that change the status of a breakpoint.
   bool processStatusChange(DebuggerClient *client);
 
+  // Returns true if the last command parsed by the client has
+  // an argument that changes the status of a breakpoint.
+  // I.e. clear, enable, disable or toggle.
   bool hasStatusChangeArg(DebuggerClient *client);
+
+  // Returns true if the last command parsed by the client has
+  // the string "enable" in its first argument position.
   bool hasEnableArg(DebuggerClient *client);
+
+  // Returns true if the last command parsed by the client has
+  // the string "disable" in its first argument position.
   bool hasDisableArg(DebuggerClient *client);
+
+  // Returns true if the last command parsed by the client has
+  // the string "clear" in its first argument position.
   bool hasClearArg(DebuggerClient *client);
+
+  // Returns true if the last command parsed by the client has
+  // the string "toggle" in its first argument position.
   bool hasToggleArg(DebuggerClient *client);
 };
 

hphp/runtime/eval/debugger/cmd/cmd_complete.cpp

@@ -45,8 +45,8 @@ bool CmdComplete::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdComplete::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdComplete::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   std::string text = client->lineRest(1);
   std::vector<std::string> res = client->getAllCompletions(text);
   for (size_t i = 0; i < res.size(); ++i) {

hphp/runtime/eval/debugger/cmd/cmd_complete.h

@@ -30,10 +30,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_config.cpp

@@ -33,8 +33,8 @@ bool CmdConfig::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdConfig::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdConfig::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 0) {
     listVars(client);
     return true;

hphp/runtime/eval/debugger/cmd/cmd_config.h

@@ -28,8 +28,10 @@ public:
   CmdConfig() : DebuggerCommand(KindOfConfig) {}
 
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 private:
   void listVars(DebuggerClient *client);
 };

hphp/runtime/eval/debugger/cmd/cmd_constant.cpp

@@ -49,8 +49,8 @@ bool CmdConstant::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdConstant::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdConstant::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   String text;
   if (client->argCount() == 1) {

hphp/runtime/eval/debugger/cmd/cmd_constant.h

@@ -29,11 +29,11 @@ public:
 
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_down.cpp

@@ -37,8 +37,8 @@ bool CmdDown::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdDown::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdDown::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() > 1) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_down.h

@@ -28,8 +28,10 @@ public:
   CmdDown() : DebuggerCommand(KindOfDown) {}
 
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 };
 
 ///////////////////////////////////////////////////////////////////////////////

hphp/runtime/eval/debugger/cmd/cmd_eval.cpp

@@ -36,7 +36,7 @@ void CmdEval::recvImpl(DebuggerThriftBuffer &thrift) {
   thrift.read(m_bypassAccessCheck);
 }
 
-bool CmdEval::onClient(DebuggerClient *client) {
+bool CmdEval::onClientImpl(DebuggerClient *client) {
   m_body = client->getCode();
   m_frame = client->getFrame();
   m_bypassAccessCheck = client->getDebuggerBypassCheck();

hphp/runtime/eval/debugger/cmd/cmd_eval.h

@@ -27,13 +27,13 @@ class CmdEval : public DebuggerCommand {
 public:
   CmdEval() : DebuggerCommand(KindOfEval), m_bypassAccessCheck(false) {}
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
   virtual void handleReply(DebuggerClient *client);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_example.cpp

@@ -55,8 +55,8 @@ bool CmdExample::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdExample::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdExample::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 1) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_example.h

@@ -28,10 +28,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_exception.cpp

@@ -67,8 +67,8 @@ bool CmdException::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdException::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdException::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 0) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_exception.h

@@ -31,8 +31,10 @@ public:
 
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 };
 
 ///////////////////////////////////////////////////////////////////////////////

hphp/runtime/eval/debugger/cmd/cmd_extended.cpp

@@ -102,7 +102,7 @@ bool CmdExtended::helpCommands(DebuggerClient *client,
   return true;
 }
 
-bool CmdExtended::onClient(DebuggerClient *client) {
+bool CmdExtended::onClientImpl(DebuggerClient *client) {
   if (client->arg(1, "help") || client->arg(1, "?")) {
     if (client->argCount() == 1) {
       return help(client);

hphp/runtime/eval/debugger/cmd/cmd_extended.h

@@ -37,7 +37,6 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
   // so CmdUser can override these functions
@@ -47,6 +46,7 @@ public:
   virtual bool invokeClient(DebuggerClient *client, const std::string &cls);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   void helpImpl(DebuggerClient *client, const char *name);
 
 private:

hphp/runtime/eval/debugger/cmd/cmd_extension.cpp

@@ -73,8 +73,8 @@ bool CmdExtension::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdExtension::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdExtension::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   m_args = *client->args();
 

hphp/runtime/eval/debugger/cmd/cmd_extension.h

@@ -28,10 +28,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_flow_control.cpp

@@ -39,8 +39,8 @@ void CmdFlowControl::recvImpl(DebuggerThriftBuffer &thrift) {
   thrift.read(m_smallStep);
 }
 
-bool CmdFlowControl::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdFlowControl::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   client->setFrame(0);
 

hphp/runtime/eval/debugger/cmd/cmd_flow_control.h

@@ -47,7 +47,6 @@ public:
       m_count(1) { }
   virtual ~CmdFlowControl();
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
   // Work done to setup a new flow command, after receiving it from the client.
@@ -64,6 +63,7 @@ public:
   bool needsVMInterrupt() { return m_needsVMInterrupt; }
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_frame.cpp

@@ -37,8 +37,8 @@ bool CmdFrame::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdFrame::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdFrame::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() != 1) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_frame.h

@@ -28,8 +28,10 @@ public:
   CmdFrame() : DebuggerCommand(KindOfFrame) {}
 
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 };
 
 ///////////////////////////////////////////////////////////////////////////////

hphp/runtime/eval/debugger/cmd/cmd_global.cpp

@@ -48,8 +48,8 @@ bool CmdGlobal::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdGlobal::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdGlobal::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   String text;
   if (client->argCount() == 1) {

hphp/runtime/eval/debugger/cmd/cmd_global.h

@@ -29,11 +29,11 @@ public:
 
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_help.cpp

@@ -278,8 +278,8 @@ bool CmdHelp::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdHelp::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdHelp::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   if (client->argCount() == 0) {
     HelpAll(client);

hphp/runtime/eval/debugger/cmd/cmd_help.h

@@ -33,7 +33,9 @@ public:
 
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 
 private:
   bool processTutorial(DebuggerClient *client);

hphp/runtime/eval/debugger/cmd/cmd_info.cpp

@@ -145,8 +145,8 @@ void CmdInfo::parseOneArg(DebuggerClient *client, string &subsymbol) {
   }
 }
 
-bool CmdInfo::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdInfo::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   string subsymbol;
 

hphp/runtime/eval/debugger/cmd/cmd_info.h

@@ -35,7 +35,6 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
   bool parseZeroArg(DebuggerClient *client);
@@ -44,6 +43,7 @@ public:
   static String FindSubSymbol(CArrRef symbols, const std::string &symbol);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_instrument.cpp

@@ -56,8 +56,8 @@ bool CmdInstrument::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdInstrument::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdInstrument::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 1) {
     if (client->argValue(1) == "list" || client->argValue(1) == "l") {
       listInst(client);

hphp/runtime/eval/debugger/cmd/cmd_instrument.h

@@ -31,10 +31,10 @@ public:
 
   virtual bool help(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_interrupt.cpp

@@ -129,7 +129,7 @@ std::string CmdInterrupt::desc() const {
   return "";
 }
 
-bool CmdInterrupt::onClient(DebuggerClient *client) {
+bool CmdInterrupt::onClientImpl(DebuggerClient *client) {
   client->setCurrentLocation(m_threadId, m_bpi);
   if (!client->getDebuggerSmallStep()) {
     // Adjust line and char if it's not small stepping

hphp/runtime/eval/debugger/cmd/cmd_interrupt.h

@@ -44,7 +44,6 @@ public:
   std::string desc() const;
   std::string error() const { return m_errorMsg;}
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
@@ -54,6 +53,7 @@ public:
   InterruptSite *getSite() { return m_site;}
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_list.cpp

@@ -24,6 +24,7 @@ namespace HPHP { namespace Eval {
 
 TRACE_SET_MOD(debugger);
 
+// Serializes this command into the given Thrift buffer.
 void CmdList::sendImpl(DebuggerThriftBuffer &thrift) {
   DebuggerCommand::sendImpl(thrift);
   thrift.write(m_file);
@@ -32,6 +33,7 @@ void CmdList::sendImpl(DebuggerThriftBuffer &thrift) {
   thrift.write(m_code);
 }
 
+// Deserializes a CmdList from the given Thrift buffer.
 void CmdList::recvImpl(DebuggerThriftBuffer &thrift) {
   DebuggerCommand::recvImpl(thrift);
   thrift.read(m_file);
@@ -40,10 +42,14 @@ void CmdList::recvImpl(DebuggerThriftBuffer &thrift) {
   thrift.read(m_code);
 }
 
+// Informs the client of all strings that may follow a list command.
+// Used for auto completion. The client uses the prefix of the argument
+// following the command to narrow down the list displayed to the user.
 void CmdList::list(DebuggerClient *client) {
   client->addCompletion(DebuggerClient::AutoCompleteFileNames);
 }
 
+// The text to display when the debugger client processes "help break".
 bool CmdList::help(DebuggerClient *client) {
   client->helpTitle("List Command");
   client->helpCmds(
@@ -70,7 +76,7 @@ bool CmdList::help(DebuggerClient *client) {
     "\n"
     "Hit return to display more lines of code after current display.\n"
     "\n"
-    "When a directory name is specified, this will be set to root directory "
+    "When a directory name is specified, this will become a root directory "
     "for resolving relative paths of PHP files. Files with absolute paths "
     "will not be affected by this setting. This directory will be stored "
     "in configuration file for future sessions as well."
@@ -167,8 +173,8 @@ bool CmdList::listFunctionOrClass(DebuggerClient *client) {
   return false;
 }
 
-bool CmdList::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdList::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() > 1) {
     return help(client);
   }
@@ -295,6 +301,9 @@ bool CmdList::onServer(DebuggerProxy *proxy) {
   return proxy->sendToClient(this);
 }
 
+// Sends a "list file" command to the proxy attached to the given client.
+// Returns false if the file does not exist or could not be read or an
+// HPHP::String instance containing the contents of the file.
 Variant CmdList::GetSourceFile(DebuggerClient *client,
                                const std::string &file) {
   CmdList cmd;

hphp/runtime/eval/debugger/cmd/cmd_list.h

@@ -27,31 +27,62 @@ class CmdList : public DebuggerCommand {
 public:
   CmdList() : DebuggerCommand(KindOfList) {}
 
+  // Sends a "list file" command to the proxy attached to the given client.
+  // Returns false if the file does not exist or could not be read or an
+  // HPHP::String instance containing the contents of the file.
   static Variant GetSourceFile(DebuggerClient *client,
                                const std::string &file);
 
+  // Informs the client of all strings that may follow a list command.
+  // Used for auto completion. The client uses the prefix of the argument
+  // following the command to narrow down the list displayed to the user.
   virtual void list(DebuggerClient *client);
+
+  // The text to display when the debugger client processes "help break".
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
+  // Puts the specified range of the contents of the source file referenced
+  // by this command in m_code and sends a copy of the updated command back
+  // to the client.
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  // Verifies the arguments of this command, sends the command to the
+  // server to get back the listing, updates the client with the current
+  // position in the source file and displays a list of source lines to
+  // the console.
+  virtual bool onClientImpl(DebuggerClient *client);
+
+  // Serializes this command into the given Thrift buffer.
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
+
+  // Deserializes a CmdList from the given Thrift buffer.
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 
 private:
+  // A path to a source file. If relative this is relative to url
+  // loaded into the server (if any).
   std::string m_file;
+
+  // The first line of the range of source lines to be listed.
   int32_t m_line1;
+
+  //The last line of the range of source lines to be listed.
   int32_t m_line2;
+
+  // If null, this is uninitialized. If false, there is no such range/file.
+  // Otherwise, this contains an HPHP::String instance representing the
+  // range of source text to be listed by this command.
   Variant m_code;
 
   bool listCurrent(DebuggerClient *client, int &line,
                    int &charFocus0, int &lineFocus1,
                    int &charFocus1);
+
   bool listFileRange(DebuggerClient *client, int line,
                      int charFocus0, int lineFocus1,
                      int charFocus1);
+
   bool listFunctionOrClass(DebuggerClient *client);
 
 };

hphp/runtime/eval/debugger/cmd/cmd_machine.cpp

@@ -193,8 +193,8 @@ void CmdMachine::UpdateIntercept(DebuggerClient *client,
   client->xend<CmdMachine>(&cmd);
 }
 
-bool CmdMachine::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdMachine::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 0) return help(client);
 
   bool rpc = client->arg(1, "rpc");

hphp/runtime/eval/debugger/cmd/cmd_machine.h

@@ -40,10 +40,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_macro.cpp

@@ -64,8 +64,8 @@ void CmdMacro::processList(DebuggerClient *client) {
   }
 }
 
-bool CmdMacro::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdMacro::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 0) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_macro.h

@@ -29,7 +29,9 @@ public:
 
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 
 private:
   void processList(DebuggerClient *client);

hphp/runtime/eval/debugger/cmd/cmd_print.cpp

@@ -287,8 +287,8 @@ void CmdPrint::handleReply(DebuggerClient *client) {
   client->output(m_ret);
 }
 
-bool CmdPrint::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdPrint::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 0) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_print.h

@@ -35,7 +35,6 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
@@ -45,6 +44,7 @@ public:
   virtual void handleReply(DebuggerClient *client);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_quit.cpp

@@ -37,9 +37,9 @@ bool CmdQuit::help(DebuggerClient *client) {
 
 // Carries out the Quit command by informing the server the client
 // is going away and then getting the client to quit.
-bool CmdQuit::onClient(DebuggerClient *client) {
-  TRACE(2, "CmdQuit::onClient\n");
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdQuit::onClientImpl(DebuggerClient *client) {
+  TRACE(2, "CmdQuit::onClientImpl\n");
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   if (client->argCount() == 0) {
     client->sendToServer(this);

hphp/runtime/eval/debugger/cmd/cmd_quit.h

@@ -30,9 +30,10 @@ public:
   // The text to display when the debugger client processes "help quit".
   virtual bool help(DebuggerClient *client);
 
+protected:
   // Carries out the Quit command by informing the server the client
   // is going away and then getting the client to quit.
-  virtual bool onClient(DebuggerClient *client);
+  virtual bool onClientImpl(DebuggerClient *client);
 
 };
 

hphp/runtime/eval/debugger/cmd/cmd_run.cpp

@@ -55,8 +55,8 @@ bool CmdRun::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdRun::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdRun::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   m_args = StringVecPtr(client->args(), null_deleter());
   m_smallStep = client->getDebuggerSmallStep();

hphp/runtime/eval/debugger/cmd/cmd_run.h

@@ -30,10 +30,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_shell.cpp

@@ -49,8 +49,8 @@ bool CmdShell::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdShell::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdShell::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() == 0) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_shell.h

@@ -30,10 +30,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_signal.cpp

@@ -31,7 +31,7 @@ void CmdSignal::recvImpl(DebuggerThriftBuffer &thrift) {
   thrift.read(m_signum);
 }
 
-bool CmdSignal::onClient(DebuggerClient *client) {
+bool CmdSignal::onClientImpl(DebuggerClient *client) {
   m_signum = client->pollSignal();
   client->sendToServer(this);
   return true;

hphp/runtime/eval/debugger/cmd/cmd_signal.h

@@ -36,10 +36,10 @@ public:
 
   Signal getSignal() const { return (Signal)m_signum;}
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_thread.cpp

@@ -101,8 +101,8 @@ void CmdThread::processList(DebuggerClient *client, bool output /* = true */) {
   }
 }
 
-bool CmdThread::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdThread::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() > 1) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_thread.h

@@ -31,10 +31,10 @@ public:
   virtual void list(DebuggerClient *client);
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_up.cpp

@@ -51,8 +51,8 @@ int CmdUp::ParseNumber(DebuggerClient *client) {
   return 1;
 }
 
-bool CmdUp::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdUp::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() > 1) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_up.h

@@ -31,8 +31,11 @@ public:
   CmdUp() : DebuggerCommand(KindOfUp) {}
 
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
+
 };
 
 ///////////////////////////////////////////////////////////////////////////////

hphp/runtime/eval/debugger/cmd/cmd_variable.cpp

@@ -111,8 +111,8 @@ void CmdVariable::PrintVariables(DebuggerClient *client, CArrRef variables,
   }
 }
 
-bool CmdVariable::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdVariable::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   String text;
   if (client->argCount() == 1) {

hphp/runtime/eval/debugger/cmd/cmd_variable.h

@@ -34,11 +34,11 @@ public:
 
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_where.cpp

@@ -73,8 +73,8 @@ Array CmdWhere::fetchStackTrace(DebuggerClient *client) {
   return st;
 }
 
-bool CmdWhere::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdWhere::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
   if (client->argCount() > 1) {
     return help(client);
   }

hphp/runtime/eval/debugger/cmd/cmd_where.h

@@ -29,7 +29,6 @@ public:
 
   virtual bool help(DebuggerClient *client);
 
-  virtual bool onClient(DebuggerClient *client);
   virtual void setClientOutput(DebuggerClient *client);
   virtual bool onServer(DebuggerProxy *proxy);
 
@@ -37,6 +36,7 @@ public:
   void processStackTrace(); // server side
 
 protected:
+  virtual bool onClientImpl(DebuggerClient *client);
   virtual void sendImpl(DebuggerThriftBuffer &thrift);
   virtual void recvImpl(DebuggerThriftBuffer &thrift);
 

hphp/runtime/eval/debugger/cmd/cmd_zend.cpp

@@ -38,8 +38,8 @@ bool CmdZend::help(DebuggerClient *client) {
   return true;
 }
 
-bool CmdZend::onClient(DebuggerClient *client) {
-  if (DebuggerCommand::onClient(client)) return true;
+bool CmdZend::onClientImpl(DebuggerClient *client) {
+  if (DebuggerCommand::onClientImpl(client)) return true;
 
   if (client->argCount() == 0) {
     const std::string &code = client->getCode();

hphp/runtime/eval/debugger/cmd/cmd_zend.h

@@ -28,7 +28,9 @@ public:
   CmdZend() : DebuggerCommand(KindOfZend) {}
 
   virtual bool help(DebuggerClient *client);
-  virtual bool onClient(DebuggerClient *client);
+
+protected:
+  virtual bool onClientImpl(DebuggerClient *client);
 };
 
 ///////////////////////////////////////////////////////////////////////////////

hphp/runtime/eval/debugger/debugger_client.cpp

@@ -985,7 +985,7 @@ DebuggerCommandPtr DebuggerClient::waitForNextInterrupt() {
         return DebuggerCommandPtr();
       }
       if (cmd->is(DebuggerCommand::KindOfSignal)) {
-        if (!cmd->onClientD(this)) {
+        if (!cmd->onClient(this)) {
           Logger::Error("Unable to handle signal command.");
           return DebuggerCommandPtr();
         }
@@ -1027,7 +1027,7 @@ void DebuggerClient::runImpl() {
           throw DebuggerServerLostException();
         }
         if (cmd->is(DebuggerCommand::KindOfSignal)) {
-          if (!cmd->onClientD(this)) {
+          if (!cmd->onClient(this)) {
             Logger::Error("%s: unable to poll signal", func);
             return;
           }
@@ -1040,7 +1040,7 @@ void DebuggerClient::runImpl() {
         m_sigTime = 0;
         usageLogInterrupt(cmd);
         {
-          if (!cmd->onClientD(this)) {
+          if (!cmd->onClient(this)) {
             Logger::Error("%s: unable to process %d", func, cmd->getType());
             return;
           }
@@ -1608,6 +1608,7 @@ do {                                         \
 #undef NEW_CMD_NAME
 }
 
+// Carries out the current command and returns true if the command completed.
 bool DebuggerClient::process() {
   TRACE(2, "DebuggerClient::process\n");
   clearCachedLocal();
@@ -1633,7 +1634,7 @@ bool DebuggerClient::process() {
     case '?': {
       if (match("?")) {
         usageLog("help", m_line);
-        return CmdHelp().onClientD(this);
+        return CmdHelp().onClient(this);
       }
       if (match("?>")) return processEval();
       break;
@@ -1644,7 +1645,7 @@ bool DebuggerClient::process() {
         usageLog(m_commandCanonical, m_line);
         if (cmd->is(DebuggerCommand::KindOfRun)) playMacro("startup");
         DebuggerCommandPtr deleter(cmd);
-        return cmd->onClientD(this);
+        return cmd->onClient(this);
       } else {
         return processTakeCode();
       }
@@ -1853,7 +1854,7 @@ DebuggerCommandPtr DebuggerClient::recvFromServer(int expected) {
     }
 
     // eval() can cause more breakpoints
-    if (!res->onClientD(this) || !console()) {
+    if (!res->onClient(this) || !console()) {
       if (m_quitting) {
         throw DebuggerClientExitException();
       } else {
@@ -1928,7 +1929,7 @@ bool DebuggerClient::processEval() {
   m_runState = Running;
   m_inputState = TakingCommand;
   m_acLiveListsDirty = true;
-  CmdEval().onClientD(this);
+  CmdEval().onClient(this);
   return true;
 }
 
@@ -1986,6 +1987,11 @@ DThreadInfoPtr DebuggerClient::getThread(int index) const {
   return DThreadInfoPtr();
 }
 
+// Retrieves a source location that is the current focus of the
+// debugger. The current focus is initially determined by the
+// breakpoint where the debugger is currently stopped and can
+// thereafter be modified by list commands and by switching the
+// the stack frame.
 void DebuggerClient::getListLocation(std::string &file, int &line,
                                      int &lineFocus0, int &charFocus0,
                                      int &lineFocus1, int &charFocus1) {

hphp/runtime/eval/debugger/debugger_client.h

@@ -125,6 +125,7 @@ public:
    * Main processing functions.
    */
   bool console();
+  // Carries out the current command and returns true if the command completed.
   bool process();
   void quit();
   void onSignal(int sig);
@@ -166,9 +167,8 @@ public:
   void tutorial(const char *text);
   void setTutorial(int mode);
 
-  /**
-   * Input functions.
-   */
+  // Returns the source code string that the debugger is currently
+  // evaluating.
   const std::string &getCode() const { return m_code;}
   void swapHelp();
 
@@ -234,8 +234,15 @@ public:
   void setMatchedBreakPoints(BreakPointInfoPtrVec breakpoints);
   void setCurrentLocation(int64_t threadId, BreakPointInfoPtr breakpoint);
   BreakPointInfoPtrVec *getMatchedBreakPoints() { return &m_matched;}
+
+  // Retrieves a source location that is the current focus of the
+  // debugger. The current focus is initially determined by the
+  // breakpoint where the debugger is currently stopped and can
+  // thereafter be modified by list commands and by switching the
+  // the stack frame.
   void getListLocation(std::string &file, int &line, int &lineFocus0,
                        int &charFocus0, int &lineFocus1, int &charFocus1);
+
   void setListLocation(const std::string &file, int line, bool center);
   void setSourceRoot(const std::string &sourceRoot);
 
@@ -385,6 +392,7 @@ private:
   bool m_acProtoTypePrompted;
 
   std::string m_line;
+  // The current command to process.
   std::string m_command;
   std::string m_commandCanonical;
   std::string m_prevCmd;

hphp/runtime/eval/debugger/debugger_command.cpp

@@ -157,17 +157,17 @@ bool DebuggerCommand::help(DebuggerClient *client) {
 // If the first argument of the command is "help" or "?"
 // this displays help text for the command and returns true.
 // Otherwise it returns false.
-bool DebuggerCommand::onClient(DebuggerClient *client) {
-  TRACE(2, "DebuggerCommand::onClient\n");
+bool DebuggerCommand::onClientImpl(DebuggerClient *client) {
+  TRACE(2, "DebuggerCommand::onClientImpl\n");
   if (client->arg(1, "help") || client->arg(1, "?")) {
     return help(client);
   }
   return false;
 }
 
-bool DebuggerCommand::onClientD(DebuggerClient *client) {
-  TRACE(2, "DebuggerCommand::onClientD\n");
-  bool ret = onClient(client);
+bool DebuggerCommand::onClient(DebuggerClient *client) {
+  TRACE(2, "DebuggerCommand::onClient\n");
+  bool ret = onClientImpl(client);
   if (client->isApiMode() && !m_incomplete) {
     setClientOutput(client);
   }

hphp/runtime/eval/debugger/debugger_command.h

@@ -90,34 +90,55 @@ public:
       m_incomplete(false) {}
 
   bool is(Type type) const { return m_type == type;}
+
   Type getType() const { return m_type;}
 
   bool send(DebuggerThriftBuffer &thrift);
+
   bool recv(DebuggerThriftBuffer &thrift);
 
+  // Informs the client of all strings that may follow a break command.
+  // Used for auto completion. The client uses the prefix of the argument
+  // following the command to narrow down the list displayed to the user.
   virtual void list(DebuggerClient *client);
+
+  // The text to display when the debugger client
+  // processes "help <this command name>".
   virtual bool help(DebuggerClient *client);
 
-  // Client-side work for a command. Returning false indicates a failure to
-  // communicate with the server (for commands that do so).
-  virtual bool onClient(DebuggerClient *client);
-  bool onClientD(DebuggerClient *client);
+  // Carries out the command and returns true if the command completed.
+  // If the client is controlled via the API, the setClientOuput method
+  // is invoked to update the client with the command output for access
+  // via the API.
+  bool onClient(DebuggerClient *client);
+
+  // Updates the client with information about the execution of this command.
+  // This information is not used by the command line client, but can
+  // be accessed via the debugger client API exposed to PHP programs.
   virtual void setClientOutput(DebuggerClient *client);
 
   // Server-side work for a command. Returning false indicates a failure to
   // communicate with the client (for commands that do so).
   virtual bool onServer(DebuggerProxy *proxy);
 
+  // This seems to be confined to eval and print commands.
+  // It is not clear that it belongs in this interface or that the
+  // assert is safe.
   virtual void handleReply(DebuggerClient *client) { assert(false); }
 
-  /**
-   * A server command processing can set m_exitInterrupt to true to break
-   * message loop in DebuggerProxy::processInterrupt().
-   */
-  virtual bool shouldExitInterrupt() { return m_exitInterrupt;}
+  // Returns true if DebuggerProxy::processInterrupt() should return
+  // to its caller instead of processing further commands from the client.
+  bool shouldExitInterrupt() { return m_exitInterrupt;}
+
+  // Returns a non empty error message if the receipt of this command
+  // did not complete successfully.
   String getWireError() const { return m_wireError; }
 
 protected:
+  // Client-side work for a command. Returns true if the command completed
+  // successfully.
+  virtual bool onClientImpl(DebuggerClient *client);
+
   // Always called from send and must implement the subclass specific
   // logic for serializing a command to send via Thrift.
   virtual void sendImpl(DebuggerThriftBuffer &thrift);

hphp/runtime/ext/ext_debugger.cpp

@@ -550,7 +550,7 @@ Variant c_DebuggerClient::t_processcmd(CVarRef cmdName, CVarRef args) {
       raise_warning("not getting a command");
     } else if (cmd->is(DebuggerCommand::KindOfInterrupt)) {
       CmdInterruptPtr cmdInterrupt = dynamic_pointer_cast<CmdInterrupt>(cmd);
-      cmdInterrupt->onClientD(m_client);
+      cmdInterrupt->onClient(m_client);
     } else {
       // Previous pending commands
       cmd->handleReply(m_client);