[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)

[Alex Langford via lldb-commits]

================
@@ -491,34 +491,42 @@ which will work like all the natively defined lldb commands. This provides a
 very flexible and easy way to extend LLDB to meet your debugging requirements.
 
 To write a python function that implements a new LLDB command define the
-function to take four arguments as follows:
+function to take five arguments as follows:
 
 ::
 
-  def command_function(debugger, command, result, internal_dict):
+  def command_function(debugger, command, exe_ctx, result, internal_dict):
       # Your code goes here
 
-Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in:
+The meaning of the arguments is given in the table below.
+
+If you provide a Python docstring in your command function LLDB will use it
+when providing "long help" for your command, as in:
 
 ::
 
   def command_function(debugger, command, result, internal_dict):
       """This command takes a lot of options and does many fancy things"""
       # Your code goes here
 
-Since lldb 3.5.2, LLDB Python commands can also take an SBExecutionContext as an
-argument. This is useful in cases where the command's notion of where to act is
-independent of the currently-selected entities in the debugger.
+though providing help can also be done programmatically (see below).
 
-This feature is enabled if the command-implementing function can be recognized
-as taking 5 arguments, or a variable number of arguments, and it alters the
-signature as such:
+Prior to lldb 3.5.2, LLDB Python command definitions didn't take the SBExecutionContext
+argument. So you may still see commands where the command definition is:
 
 ::
-
-  def command_function(debugger, command, exe_ctx, result, internal_dict):
+   
+  def command_function(debugger, command, result, internal_dict):
       # Your code goes here
 
+This form is deprecated because it can only operate on the "currently selected"
+target, process, thread, frame.  The command will behave as expected when run
+directly on the command line.  But if the command is used in a stop-hook, breakpoint
+callback, etc. where the response to the callback determines whether we will select
+this or that particular process/frame/thread, the global "currently selected"
+entity is not necessarily the one the callback is meant to handle.  In that case, this
+command definition form can't do the right thing.
----------------
bulbazord wrote:

You wrote that it's deprecated at the beginning of the paragraph, but LLDB never removes functions nor removes working implementations of deprecated functions. I would recommend wording the conclusion more strongly, e.g.
`In that case, this command definition form can't do the right thing and is therefore highly discouraged from use.`

https://github.com/llvm/llvm-project/pull/86593