A request to add proper docstrings to functions.
Closed this issue · 5 comments
First of — I really like some of the abstractions the library introduces. But exploring the library in python/ipython REPL shell is really hard without proper docstrings.
compare
In [5]: funcy.repeat?
Type: type
String Form:<type 'itertools.repeat'>
File: /Users/teferi/git/eksmo/env/lib/python2.7/lib-dynload/itertools.so
Docstring:
repeat(object [,times]) -> create an iterator which returns the object
for the specified number of times. If not specified, returns the object
endlessly.
to
In [6]: funcy.retry?
Type: function
String Form:<function retry at 0x1063a1848>
File: /Users/teferi/git/eksmo/env/lib/python2.7/site-packages/funcy/flow.py
Definition: funcy.retry(*dargs, **dkwargs)
Docstring: <no docstring>
Reading the latter really doesn't shed any light on how to use it. I understand that it's a lot of work — to properly document the whole thing, but it would be really nice to have such descriptions.
Also I'm willing to offer some help with that some time later (if that's ok =))
I'd also help with this, if we can come up with a "standard" to go from.
For now docs for everything are available on readthedocs.
And I don't want to have duplicate texts in docs and docstrings. I know there is an autodoc for that, but docs and docstrings are not perfectly compatible:
- docstrings are better succinct and docs I prefer to be more verbose with examples,
- rst and sphinx markup in docstrings will add noise.
Also, there are a couple of funcy specific issues:
- some functions are just aliases, e.g.
icat = itertools.chain.from_iterable, - some functions are paired in docs, like
flatten(),iflatten()not sure it's possible with autodoc, - some functions could be introspected poorly, e.g. when having first optional argument.
Maybe I'll just need to suck it up on first two points and try to deal with the rest gradually. Probably, start from functions not having this issues.
Anyway, if you have ideas, or some autodoc experience, I'll welcome any input.
There is an update on that. I finally set up autodoc, even added autodecorator directive in a850d7e.
Some things, namely @contextmanager, @wraps, unwrap and ContextDecorator, already use it.
Now that we have succint descriptions in cheatsheat it could make sense to copy them to docstrings. Sadly duplication seems inevitable, maybe even prefferable over some custom docs script.