Improve docstring of python-indent-def-block-scale

* lisp/progmodes/python.el (python-indent-def-block-scale): Improve
docstring.  (Bug#62696)

1 files changed, 24 insertions, 1 deletions

diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index 9ae95ecfc1c..5bb15c60956 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -1265,7 +1265,30 @@ For NODE, OVERRIDE, START, END, and ARGS, see
   :type '(repeat symbol))
 
 (defcustom python-indent-def-block-scale 2
-  "Multiplier applied to indentation inside multi-line def blocks."
+  "Multiplier applied to indentation inside multi-line blocks.
+The indentation in parens in the block header will be the current
+indentation plus `python-indent-offset' multiplied by this
+variable.  For example, the arguments are indented as follows if
+this variable is 1:
+
+    def do_something(
+        arg1,
+        arg2):
+        print('hello')
+
+if this variable is 2 (default):
+
+    def do_something(
+            arg1,
+            arg2):
+        print('hello')
+
+This variable has an effect on all blocks, not just def block.
+This variable only works if the opening paren is not followed by
+non-whitespace characters on the same line.  Modify
+`python-indent-block-paren-deeper' to customize the case where
+non-whitespace characters follow the opening paren on the same
+line."
   :version "26.1"
   :type 'integer
   :safe 'natnump)