bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index 7bc00ff..3161418 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -767,6 +767,41 @@
Don't try this at home, kids!
+.. _faq-positional-only-arguments:
+
+What does the slash(/) in the parameter list of a function mean?
+----------------------------------------------------------------
+
+A slash in the argument list of a function denotes that the parameters prior to
+it are positional-only. Positional-only parameters are the ones without an
+externally-usable name. Upon calling a function that accepts positional-only
+parameters, arguments are mapped to parameters based solely on their position.
+For example, :func:`pow` is a function that accepts positional-only parameters.
+Its documentation looks like this::
+
+ >>> help(pow)
+ Help on built-in function pow in module builtins:
+
+ pow(x, y, z=None, /)
+ Equivalent to x**y (with two arguments) or x**y % z (with three arguments)
+
+ Some types, such as ints, are able to use a more efficient algorithm when
+ invoked using the three argument form.
+
+The slash at the end of the parameter list means that all three parameters are
+positional-only. Thus, calling :func:`pow` with keyword aguments would lead to
+an error::
+
+ >>> pow(x=3, y=4)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ TypeError: pow() takes no keyword arguments
+
+Note that as of this writing this is only documentational and no valid syntax
+in Python, although there is :pep:`570`, which proposes a syntax for
+position-only parameters in Python.
+
+
Numbers and strings
===================