Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

bpo-33702: Add some missing links in production lists and do a little polish #7259

Merged
merged 7 commits into from
Jul 7, 2018
Merged

bpo-33702: Add some missing links in production lists and do a little polish #7259

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d59d9a1
Initial commit
andresdelfino May 30, 2018
e69dfc4
Second commit
andresdelfino May 30, 2018
71148b3
Third commit
andresdelfino May 30, 2018
433fba9
Fix whitespace
andresdelfino May 31, 2018
96e5d9e
Fix whitspace
andresdelfino May 31, 2018
5b7a413
Address Serhiy comments
andresdelfino Jul 7, 2018
f762477
Address new comments
andresdelfino Jul 7, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions Doc/reference/compound_stmts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ The :keyword:`if` statement is used for conditional execution:

.. productionlist::
if_stmt: "if" `expression` ":" `suite`
: ( "elif" `expression` ":" `suite` )*
: ("elif" `expression` ":" `suite`)*
: ["else" ":" `suite`]

It selects exactly one of the suites by evaluating the expressions one by one
Expand Down Expand Up @@ -235,7 +235,7 @@ The :keyword:`try` statement specifies exception handlers and/or cleanup code
for a group of statements:

.. productionlist::
try_stmt: try1_stmt | try2_stmt
try_stmt: `try1_stmt` | `try2_stmt`
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["as" `identifier`]] ":" `suite`)+
: ["else" ":" `suite`]
Expand Down Expand Up @@ -384,7 +384,7 @@ This allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally`
usage patterns to be encapsulated for convenient reuse.

.. productionlist::
with_stmt: "with" with_item ("," with_item)* ":" `suite`
with_stmt: "with" `with_item` ("," `with_item`)* ":" `suite`
with_item: `expression` ["as" `target`]

The execution of the :keyword:`with` statement with one "item" proceeds as follows:
Expand Down Expand Up @@ -468,14 +468,15 @@ A function definition defines a user-defined function object (see section
:ref:`types`):

.. productionlist::
funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite`
funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")"
: ["->" `expression`] ":" `suite`
decorators: `decorator`+
decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE
dotted_name: `identifier` ("." `identifier`)*
parameter_list: `defparameter` ("," `defparameter`)* ["," [`parameter_list_starargs`]]
: | `parameter_list_starargs`
parameter_list_starargs: "*" [`parameter`] ("," `defparameter`)* ["," ["**" `parameter` [","]]]
: | "**" `parameter` [","]
parameter_list: `defparameter` ("," `defparameter`)*
: ["," [`parameter_list_starargs`]] | `parameter_list_starargs`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is better to left this and the following production lists as is.

parameter_list_starargs: "*" [`parameter`] ("," `defparameter`)*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is better to break a line before | than at arbitrary place. I think it is better to keep the existing formatting. It is not much longer that the previous production list.

: ["," ["**" `parameter` [","]]] | "**" `parameter` [","]
parameter: `identifier` [":" `expression`]
defparameter: `parameter` ["=" `expression`]
funcname: `identifier`
Expand Down Expand Up @@ -698,7 +699,8 @@ Coroutine function definition
-----------------------------

.. productionlist::
async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`] ":" `suite`
async_funcdef: [`decorators`] "async" "def" `funcname` "(" [`parameter_list`] ")"
: ["->" `expression`] ":" `suite`

.. index::
keyword: async
Expand Down
18 changes: 9 additions & 9 deletions Doc/reference/expressions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -816,7 +816,7 @@ or list). Slicings may be used as expressions or as targets in assignment or
slicing: `primary` "[" `slice_list` "]"
slice_list: `slice_item` ("," `slice_item`)* [","]
slice_item: `expression` | `proper_slice`
proper_slice: [`lower_bound`] ":" [`upper_bound`] [ ":" [`stride`] ]
proper_slice: [`lower_bound`] ":" [`upper_bound`] [":" [`stride`]]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a space between ]'s increase readability. And the space after [ was added for symmetry.

lower_bound: `expression`
upper_bound: `expression`
stride: `expression`
Expand Down Expand Up @@ -862,7 +862,7 @@ series of :term:`arguments <argument>`:
.. productionlist::
call: `primary` "(" [`argument_list` [","] | `comprehension`] ")"
argument_list: `positional_arguments` ["," `starred_and_keywords`]
: ["," `keywords_arguments`]
: ["," `keywords_arguments`]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left it as is. Extra spaces help to see a difference between the continuation and the alternation.

: | `starred_and_keywords` ["," `keywords_arguments`]
: | `keywords_arguments`
positional_arguments: ["*"] `expression` ("," ["*"] `expression`)*
Expand Down Expand Up @@ -1055,7 +1055,7 @@ The power operator binds more tightly than unary operators on its left; it binds
less tightly than unary operators on its right. The syntax is:

.. productionlist::
power: ( `await_expr` | `primary` ) ["**" `u_expr`]
power: (`await_expr` | `primary`) ["**" `u_expr`]

Thus, in an unparenthesized sequence of power and unary operators, the operators
are evaluated from right to left (this does not constrain the evaluation order
Expand Down Expand Up @@ -1127,7 +1127,7 @@ operators and one for additive operators:

.. productionlist::
m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "@" `m_expr` |
: `m_expr` "//" `u_expr`| `m_expr` "/" `u_expr` |
: `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` |
: `m_expr` "%" `u_expr`
a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr`

Expand Down Expand Up @@ -1205,7 +1205,7 @@ Shifting operations
The shifting operations have lower priority than the arithmetic operations:

.. productionlist::
shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr`
shift_expr: `a_expr` | `shift_expr` ("<<" | ">>") `a_expr`

These operators accept integers as arguments. They shift the first argument to
the left or right by the number of bits given by the second argument.
Expand Down Expand Up @@ -1265,7 +1265,7 @@ C, expressions like ``a < b < c`` have the interpretation that is conventional
in mathematics:

.. productionlist::
comparison: `or_expr` ( `comp_operator` `or_expr` )*
comparison: `or_expr` (`comp_operator` `or_expr`)*
comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!="
: | "is" ["not"] | ["not"] "in"

Expand Down Expand Up @@ -1629,9 +1629,9 @@ Expression lists
.. index:: pair: expression; list

.. productionlist::
expression_list: `expression` ( "," `expression` )* [","]
starred_list: `starred_item` ( "," `starred_item` )* [","]
starred_expression: `expression` | ( `starred_item` "," )* [`starred_item`]
expression_list: `expression` ("," `expression`)* [","]
starred_list: `starred_item` ("," `starred_item`)* [","]
starred_expression: `expression` | (`starred_item` ",")* [`starred_item`]
starred_item: `expression` | "*" `or_expr`

.. index:: object: tuple
Expand Down
2 changes: 1 addition & 1 deletion Doc/reference/lexical_analysis.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -621,7 +621,7 @@ for the contents of the string is:
f_string: (`literal_char` | "{{" | "}}" | `replacement_field`)*
replacement_field: "{" `f_expression` ["!" `conversion`] [":" `format_spec`] "}"
f_expression: (`conditional_expression` | "*" `or_expr`)
: ("," `conditional_expression` | "," "*" `or_expr`)* [","]
: ("," `conditional_expression` | "," "*" `or_expr`)* [","]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above.

: | `yield_expression`
conversion: "s" | "r" | "a"
format_spec: (`literal_char` | NULL | `replacement_field`)*
Expand Down
22 changes: 10 additions & 12 deletions Doc/reference/simple_stmts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -707,15 +707,14 @@ The :keyword:`import` statement
keyword: from

.. productionlist::
import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )*
: | "from" `relative_module` "import" `identifier` ["as" `name`]
: ( "," `identifier` ["as" `name`] )*
: | "from" `relative_module` "import" "(" `identifier` ["as" `name`]
: ( "," `identifier` ["as" `name`] )* [","] ")"
import_stmt: "import" `module` ["as" `identifier`] ("," `module` ["as" `identifier`])*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why name was replaced by identifier?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because, when I added a link to name in future statements, it linked to the name in import statements. That's why I replaced name in both places to "identifier". Perhaps it can be solved in other way?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see, the problem was that name was defined in two places. Then using an identifier LGTM. In the Grammar file the same term is used for the names before and after 'as' in import_from.

: | "from" `relative_module` "import" `identifier` ["as" `identifier`]
: ("," `identifier` ["as" `identifier`])*
: | "from" `relative_module` "import" "(" `identifier` ["as" `identifier`]
: ("," `identifier` ["as" `identifier`])* [","] ")"
: | "from" `module` "import" "*"
module: (`identifier` ".")* `identifier`
relative_module: "."* `module` | "."+
name: `identifier`

The basic import statement (no :keyword:`from` clause) is executed in two
steps:
Expand Down Expand Up @@ -837,12 +836,11 @@ features on a per-module basis before the release in which the feature becomes
standard.

.. productionlist:: *
future_statement: "from" "__future__" "import" feature ["as" name]
: ("," feature ["as" name])*
: | "from" "__future__" "import" "(" feature ["as" name]
: ("," feature ["as" name])* [","] ")"
feature: identifier
name: identifier
future_stmt: "from" "__future__" "import" `feature` ["as" `identifier`]
: ("," `feature` ["as" `identifier`])*
: | "from" "__future__" "import" "(" `feature` ["as" `identifier`]
: ("," `feature` ["as" `identifier`])* [","] ")"
feature: `identifier`

A future statement must appear near the top of the module. The only lines that
can appear before a future statement are:
Expand Down