Document the "extra_args" parameter to scripted breakpoint callbacks

[jingham]

Summary

I forgot to document this when adding the feature. Added docs here in both the python-reference.rst and in the command help.

[JDevlieghere]

LGTM

[kastiglione]

lldb/source/Commands/CommandObjectBreakpointCommand.cpp

127

How about internal_dict, the name used elsewhere, and since in this example dict would shadow the python dict() constructor.

[jingham]

lldb/source/Commands/CommandObjectBreakpointCommand.cpp

127

Did this as a follow-on.

lldb/docs/use/python-reference.rst

 code, the code is executed as the body of a function which takes three
 arguments:
 
 ::
 
   def breakpoint_function_wrapper(frame, bp_loc, dict):
      # Your code goes here
 
+or:
 
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| Argument   | Type                          | Description                                                                                                                               |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| **frame**  | **lldb.SBFrame**              | The current stack frame where the breakpoint got hit.                                                                                     |
-|            |                               | The object will always be valid.                                                                                                          |
-|            |                               | This **frame** argument might *not* match the currently selected stack frame found in the **lldb** module global variable **lldb.frame**. |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| **bp_loc** | **lldb.SBBreakpointLocation** | The breakpoint location that just got hit. Breakpoints are represented by **lldb.SBBreakpoint**                                           |
-|            |                               | objects. These breakpoint objects can have one or more locations. These locations                                                         |
-|            |                               | are represented by **lldb.SBBreakpointLocation** objects.                                                                                 |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| **dict**   | **dict**                      | The python session dictionary as a standard python dictionary object.                                                                     |
-+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+::
+
+  def breakpoint_function_wrapper(frame, bp_loc, extra_args, dict):
+     # Your code goes here
+
+
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| Argument       | Type                          | Description                                                                                                                               |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **frame**      | **lldb.SBFrame**              | The current stack frame where the breakpoint got hit.                                                                                     |
+|                |                               | The object will always be valid.                                                                                                          |
+|                |                               | This **frame** argument might *not* match the currently selected stack frame found in the **lldb** module global variable **lldb.frame**. |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **bp_loc**     | **lldb.SBBreakpointLocation** | The breakpoint location that just got hit. Breakpoints are represented by **lldb.SBBreakpoint**                                           |
+|                |                               | objects. These breakpoint objects can have one or more locations. These locations                                                         |
+|                |                               | are represented by **lldb.SBBreakpointLocation** objects.                                                                                 |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **extra_args** | **lldb.SBStructuredData**     | **Optional** If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its      |
+|                |                               | contents can parametrize this use of the callback.  For instance, instead of writing a callback that stops when the caller is "Foo",      |
+|                |                               | you could take the function name from a field in the **extra_args**, making the callback more general.  The **-k** and **-v** options     |
+|                |                               | to **breakpoint command add** will be passed as a Dictionary in the **extra_args** parameter, or you can provide it with the SB API's.    |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| **dict**       | **dict**                      | The python session dictionary as a standard python dictionary object.                                                                     |
++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
 
 Optionally, a Python breakpoint command can return a value. Returning False
 tells LLDB that you do not want to stop at the breakpoint. Any other return
 value (including None or leaving out the return statement altogether) is akin
 to telling LLDB to actually stop at the breakpoint. This can be useful in
 situations where a breakpoint only needs to stop the process when certain
 conditions are met, and you do not want to inspect the program state manually
 at every stop and then continue.

lldb/source/Commands/CommandObjectBreakpointCommand.cpp

 
 )"
         "When specifying a python function with the --python-function option, you need \
 to supply the function name prepended by the module name:"
         R"(
 
     --python-function myutils.breakpoint_callback
 
-The function itself must have the following prototype:
+The function itself must have either of the following prototypes:
 
 def breakpoint_callback(frame, bp_loc, dict):
   # Your code goes here
 
+or:
+
+def breakpoint_callback(frame, bp_loc, extra_args, dict):
+  # Your code goes here
+
 )"
         "The arguments are the same as the arguments passed to generated functions as \
-described above.  Note that the global variable 'lldb.frame' will NOT be updated when \
+described above.  In the second form, any -k and -v pairs provided to the command will \ 
+be packaged into a SBDictionary in an SBStructuredData and passed as the extra_args parameter. \
+\n\n\  
+Note that the global variable 'lldb.frame' will NOT be updated when \
 this function is called, so be sure to use the 'frame' argument. The 'frame' argument \
 can get you to the thread via frame.GetThread(), the thread can get you to the \
 process via thread.GetProcess(), and the process can get you back to the target \
 via process.GetTarget()."
         R"(
 
 )"
         "Important Note: As Python code gets collected into functions, access to global \