Make the correct (5 argument) form of the command definition be the primary one suggested in the docs

[jimingham]

This has been available for years now, so it should be safe to always use it.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: None (jimingham)

Changes

This has been available for years now, so it should be safe to always use it.

---

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

1 Files Affected:

• (modified) lldb/docs/use/python-reference.rst (+19-11)

diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst
index e5195a2471d9af..bafbe812383d69 100644
--- a/lldb/docs/use/python-reference.rst
+++ b/lldb/docs/use/python-reference.rst
@@ -491,14 +491,17 @@ 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:
 
 ::
 
@@ -506,19 +509,24 @@ Optionally, you can also provide a Python docstring, and LLDB will use it when p
       """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.
+
 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
 | Argument          | Type                           | Description                                                                                                                      |
 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+

[bulbazord]

LGTM

[bulbazord]

nit: Spurious whitespace

[bulbazord]

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.