From e428092d6111aedae0d532def2d88a37a0035405 Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 29 Jul 2020 16:48:05 +0200 Subject: [PATCH 1/3] mention the option to document default values in the type spec --- doc/format.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/format.rst b/doc/format.rst index 9f9744b9..2ab05f66 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -197,6 +197,13 @@ The sections of a function's docstring are: Description of parameter `x` (the default is -1, which implies summation over all axes). + or as part of the type:: + + copy : bool, default True + dtype : data-type, default: int + + where the colon is completely optional. + When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:: From d09324efab6acf13fb6adaba52eb22acf73cbf5b Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 1 Jan 2021 13:38:48 +0000 Subject: [PATCH 2/3] Commit doc suggestion that "default" is used instead of "optional" Co-authored-by: Joel Nothman --- doc/format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/format.rst b/doc/format.rst index 2ab05f66..f6b53966 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -197,7 +197,7 @@ The sections of a function's docstring are: Description of parameter `x` (the default is -1, which implies summation over all axes). - or as part of the type:: + or as part of the type, instead of "optional":: copy : bool, default True dtype : data-type, default: int From 4ca0f9651f3677d4847149c836a20d4e771f622b Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 6 Jan 2021 00:50:43 +0100 Subject: [PATCH 3/3] show multiple different versions of the default syntax --- doc/format.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index f6b53966..fdb5afd7 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -197,12 +197,12 @@ The sections of a function's docstring are: Description of parameter `x` (the default is -1, which implies summation over all axes). - or as part of the type, instead of "optional":: + or as part of the type, instead of ``optional``. If the default value would not be + used as a value, ``optional`` is preferred. These are all equivalent:: copy : bool, default True - dtype : data-type, default: int - - where the colon is completely optional. + copy : bool, default=True + copy : bool, default: True When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first::