microsoft / microsoft/Qcodes

Docstrings for parameters

Offen
#246 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

discussion
Vorherrschende Sprache
Python
Sterne
459
Forks
359
Ø Merge
3 T. 6 Std.
Gemergte PRs (30 T.)
73

Beschreibung

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 .

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne damit, das Parameterbeispiel in diesem Issue und die frühere Diskussion in #139 zu prüfen. Ermittle, wie dynamisch geänderte Parameter in docstrings dargestellt werden sollten, einschließlich abhängiger foo{bar}-Parameter, und lege einen abgestimmten Dokumentationsansatz fest, der alle möglichen Verhaltensweisen abdeckt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.