Docstrings for parameters
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Python
- Estrellas
- 459
- Forks
- 359
- Merge medio
- 3 d 6 h
- PR fusionados (30 d)
- 73
Descripción
Given a situation like the following:
``` python
# foo driver,pseudo code
self.add_parameter('foo',
label='foo',
set_cmd='bar',
set_parser=self._set_input_config,
)
def _set_input_config(self, s):
if s in ['baz']:
self.foo.set_validator(self._VOLT_ENUM)
self._set_units('V')
else:
self.foo.set_validator(self._CURR_ENUM)
self._set_units('A')
```
The question is then how to document the parameter foo?
The same would be if one adds a foo{bar} parameter depending on some response of another parameter right ?
Two solutions not mutally exclusive:
- docstring that describe "dynamically" the parameters (may be not trivial to implement)
- describe all the possible behaviors of the parameter.
I can't come up with a docstring example for the latter case though.
Also we should just decide on what's the best, not what's doable at the moment with the current architecture.
@alexcjohnson @MerlinSmiles @Rubenknex @AdriaanRol write your opinions (tagged because you were part of the discussion in #139 .
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
Comienza revisando el ejemplo de parámetros de este issue y la discusión anterior en #139. Determina cómo deben representarse los parámetros que cambian dinámicamente en los docstrings, incluidos los parámetros foo{bar} dependientes, y establece un enfoque de documentación acordado que cubra todos los comportamientos posibles.
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
- 5/5
- Tiempo estimado
- Más de una semana
- Estado de actividad
- Estancado
- Claridad
- Necesita aclaración
- Aptitud para principiantes
- 25/100