bpo-32769: Write annotation entry for glossary by andresdelfino · Pull Request #6657 · python/cpython
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, looks good! I have just few minor comments.
| An :term:`annotation` of a function or method. | ||
|
|
||
| For example, this function is annotated as requiring its parameters to be | ||
| int and as returning an int as well:: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Make "int" text here a reference to builtin int class here (appears twice in this sentence), I think you can use :class: for this.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✔️ Done
| :func:`typing.get_type_hints`. | ||
| An :term:`annotation` of a global variable, or class variable. | ||
|
|
||
| For example, this variable is annotated as an int:: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same comment about making "int" a reference here.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✔️ Done
|
|
||
| For example, this variable is annotated as an int:: | ||
|
|
||
| count: int = 0 |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe show also an example where there is no right hand side?
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✔️ Done
| function object. | ||
| An :term:`annotation` of a function or method. | ||
|
|
||
| For example, this function is annotated as requiring its parameters to be |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"requiring" is a too strong word, I would replace with "expecting".
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✔️ Done
| An :term:`annotation` of a function or method. | ||
|
|
||
| For example, this function is annotated as requiring its parameters to be | ||
| int and as returning an int as well:: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"int" -> "an int" at beginning of this line.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Didn't use "an int" there because we are talking about two parameters, in plural. Anyway, I changed this lines a little, I hope it makes it clearer.
| :func:`typing.get_type_hints`. | ||
| An :term:`annotation` of a global variable, or class variable. | ||
|
|
||
| For example, this variable is annotated as an int:: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would reformulate it as this variable is annotated as taking :class:int values or similar.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✔️ Done
|
|
||
| count: int = 0 | ||
|
|
||
| When annotating variables, assignment is optional: |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Double colon here.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
✔️ Done
| attribute of a class or module object and can be accessed using | ||
| :func:`typing.get_type_hints`. | ||
| An :term:`annotation` of a global variable, or class variable. | ||
|
|
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this empty line is not needed
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think its best to separate a concise description of the term from the example.
If you still think it's best to put them in the same paragraph, I'll make it so :)
@ilevkivskyi should I keep "class attributes" to refer to instance variables, or should I use the later to separate between data attributes (instance variables) and behavior attributes (methods)?
I think "class attributes" is somewhat ambiguous.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like how this looks now. Thanks!
andresdelfino added a commit to andresdelfino/cpython that referenced this pull request
