Docstrings for parameters
Dieses Issue hat noch niemand übernommen.
- 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
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Ö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