microsoft / microsoft/Qcodes

Docstrings for parameters

Abierto
#246 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

discussion
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

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 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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.