bpo-32769: Write annotation entry for glossary #6657
Conversation
ilevkivskyi
left a comment
ilevkivskyi
left a comment
There was a problem hiding this comment.
Thanks, looks good! I have just few minor comments.
Doc/glossary.rst
Outdated
| 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:: |
There was a problem hiding this comment.
Make "int" text here a reference to builtin int class here (appears twice in this sentence), I think you can use :class: for this.
Doc/glossary.rst
Outdated
| :func:`typing.get_type_hints`. | ||
| An :term:`annotation` of a global variable, or class variable. | ||
|
|
||
| For example, this variable is annotated as an int:: |
There was a problem hiding this comment.
Same comment about making "int" a reference here.
|
|
||
| For example, this variable is annotated as an int:: | ||
|
|
||
| count: int = 0 |
There was a problem hiding this comment.
Maybe show also an example where there is no right hand side?
class C:
field: int
Doc/glossary.rst
Outdated
| function object. | ||
| An :term:`annotation` of a function or method. | ||
|
|
||
| For example, this function is annotated as requiring its parameters to be |
There was a problem hiding this comment.
"requiring" is a too strong word, I would replace with "expecting".
Doc/glossary.rst
Outdated
| 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:: |
There was a problem hiding this comment.
"int" -> "an int" at beginning of this line.
There was a problem hiding this comment.
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.
Doc/glossary.rst
Outdated
| :func:`typing.get_type_hints`. | ||
| An :term:`annotation` of a global variable, or class variable. | ||
|
|
||
| For example, this variable is annotated as an int:: |
There was a problem hiding this comment.
I would reformulate it as this variable is annotated as taking :class:int values or similar.
Doc/glossary.rst
Outdated
|
|
||
| count: int = 0 | ||
|
|
||
| When annotating variables, assignment is optional: |
| 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. | ||
|
|
There was a problem hiding this comment.
I think this empty line is not needed
There was a problem hiding this comment.
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. |
ilevkivskyi
left a comment
ilevkivskyi
left a comment
There was a problem hiding this comment.
I like how this looks now. Thanks!
https://bugs.python.org/issue32769 (cherry picked from commit f2290fb) Co-authored-by: Andrés Delfino <[email protected]>
4 participants
https://bugs.python.org/issue32769