From 103bfcfa05af9ddb5182605e58dc15e88bbc48e8 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Fri, 12 Aug 2022 18:23:32 -0400 Subject: [PATCH 1/2] Say how to include shape/size info --- doc/format.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/format.rst b/doc/format.rst index 56e4a4f3..7fe955fd 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -211,6 +211,20 @@ used as a value, ``optional`` is preferred. These are all equivalent:: copy : bool, default=True copy : bool, default: True +If the shapes and sizes of the parameters are related, that information +should be included in parentheses at the beginning of the type line. A +trailing comma should be included inside the parentheses if the +parameter is 1D:: + + Parameters + ---------- + a : (M,) array_like + First input vector. + b : (N,) array_like + Second input vector. + out : (M, N) ndarray, optional + A location where the result is stored + 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 301225b316b26cf4c6ca224b2cc011c9ac3735a5 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Fri, 12 Aug 2022 21:11:22 -0400 Subject: [PATCH 2/2] Revise discussion of parameter shapes and sizes --- doc/format.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 7fe955fd..a5e19155 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -211,19 +211,17 @@ used as a value, ``optional`` is preferred. These are all equivalent:: copy : bool, default=True copy : bool, default: True -If the shapes and sizes of the parameters are related, that information -should be included in parentheses at the beginning of the type line. A -trailing comma should be included inside the parentheses if the +If the shapes and sizes of the parameters are interrelated, then include +that information in parentheses immediately before the type information. +A trailing comma should be included inside the parentheses when the parameter is 1D:: - Parameters - ---------- a : (M,) array_like First input vector. b : (N,) array_like Second input vector. out : (M, N) ndarray, optional - A location where the result is stored + A location where the result is stored. 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::