python / python/cpython

The explanation of "Annotating callable objects" section should be made better

Abierto
#145,577 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

docs topic-typing
Lenguaje dominante
Python
Estrellas
77.2k
Forks
35.9k
Métricas de merge de PR
Métricas de PR pendientes

Descripción

Documentation

*Notes:

  • Python 3.14.3
  • Related: #145602

In the explanation of Annotating callable objects section, some words or sentence aren't clear, distinct, specific, concise and less common, and the word argument is misused, etc. So they should be corrected:

<Some examples>
The 1st one:

*Notes:

  • "has" is better than "takes" because "takes" sounds taking an argument but not parameter:

... a function that takes a single parameter of type int and returns a str.

... a function that has a single parameter of type int and returns a str.

The 2nd one:

*Notes:

  • Naming and calling [] "type specification" is more understandable than "subscription syntax".
  • "must" is enough for emphasis so "always" and "exactly" aren't needed, emphasizing too much.
  • "two objects" are better than "two values" because "two values" sounds actual values like v = "Hello"'s "Hello" so it's confusing while talking about types.
  • "parameter type list" is better than "argument list" because "parameter" is correct and "type list" is more specific and understandable.

The subscription syntax must always be used with exactly two values: the
argument list and the return type.

The type specification [] must have two objects, a parameter type list and return type.

etc.
Linked PRs
  • gh-145576
  • gh-145598

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Línea de trabajo

Comienza con la sección "Annotating callable objects" de la documentación de typing de Python, usando como contexto los ejemplos de redacción y las issues relacionadas #145602, #145576 y #145598. Revisa la terminología propuesta y los cambios en las oraciones; después, confirma que la sección usa de forma coherente distinciones claras entre parámetros, argumentos, objetos y tipos.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
python
Área
documentation
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
1-3 horas
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
35/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.