Python: Expand QLDoc for get[Named]ArgumentForCall

python/ql/src/semmle/python/objects/ObjectAPI.qll

@@ -352,7 +352,29 @@ class CallableValue extends Value {
         result = this.(CallableObjectInternal).getParameterByName(name)
     }
 
-    /** Gets the argument corresponding to the `n'th parameter node of this callable. */
+    /**
+     * Gets the argument in `call` corresponding to the `n`'th positional parameter of this callable.
+     *
+     * Use this method instead of `call.getArg(n)` to handle the fact that this function might be used as
+     * a bound-method, such that argument `n` of the call corresponds to the `n+1` parameter of the callable.
+     *
+     * This method also gives results when the argument is passed as a keyword argument in `call`, as long
+     * as `this` is not a builtin function or a builtin method.
+     *
+     * Examples:
+     *
+     * - if `this` represents the `PythonFunctionValue` for `def func(a, b):`, and `call` represents
+     *   `func(10, 20)`, then `getArgumentForCall(call, 0)` will give the `ControlFlowNode` for `10`.
+     *
+     * - with `call` representing `func(b=20, a=10)`, `getArgumentForCall(call, 0)` will give
+     *   the `ControlFlowNode` for `10`.
+     *
+     * - if `this` represents the `PythonFunctionValue` for `def func(self, a, b):`, and `call`
+     *   represents `foo.func(10, 20)`, then `getArgumentForCall(call, 1)` will give the
+     *   `ControlFlowNode` for `10`.
+     *   Note: There will also exist a `BoundMethodValue bm` where `bm.getArgumentForCall(call, 0)`
+     *   will give the `ControlFlowNode` for `10` (notice the shift in index used).
+     */
     cached
     ControlFlowNode getArgumentForCall(CallNode call, int n) {
         exists(ObjectInternal called, int offset |
@@ -373,7 +395,25 @@ class CallableValue extends Value {
         )
     }
 
-    /** Gets the argument corresponding to the `name`d parameter node of this callable. */
+    /**
+     * Gets the argument in `call` corresponding to the `name`d keyword parameter of this callable.
+     * ONLY WORKS FOR NON-BUILTINS.
+     *
+     * This method also gives results when the argument is passed as a positional argument in `call`, as long
+     * as `this` is not a builtin function or a builtin method.
+     *
+     * Examples:
+     *
+     * - if `this` represents the `PythonFunctionValue` for `def func(a, b):`, and `call` represents
+     *   `func(10, 20)`, then `getNamedArgumentForCall(call, "a")` will give the `ControlFlowNode` for `10`.
+     *
+     * - with `call` representing `func(b=20, a=10)`, `getNamedArgumentForCall(call, "a")` will give
+     *   the `ControlFlowNode` for `10`.
+     *
+     * - if `this` represents the `PythonFunctionValue` for `def func(self, a, b):`, and `call`
+     *   represents `foo.func(10, 20)`, then `getNamedArgumentForCall(call, "a")` will give the
+     *   `ControlFlowNode` for `10`.
+     */
     cached
     ControlFlowNode getNamedArgumentForCall(CallNode call, string name) {
         exists(CallableObjectInternal called, int offset |