Fredrik Lundh wrote:
> Kenneth McDonald wrote:
>
>>More seriously, there is a major problem with docstrings in that they
>>can only document something that has a docstring; classes, functions,
>>methods, and modules. But what if I have constants that are
>>important? The only place to document them is in the module
>>docstring, and everything else--examples, concepts, and so on--must
>>be thrown in there as well. But there are no agreed on formats and
>>processing pipelines that then allow such a large module docstring,
>>plus other docstrings, to produce a good final document.
>
> fwiw, that's one of reason why I developed PythonDoc (which supports
> JavaDoc-style documentation for all the usual suspects, but also for con-
> stants, attributes, and variables)
The one thing I dislike about PythonDoc is that it puts everything into
comments and thus docstrings are usually neglected. I spend my entire
work day at an ipython shell, which makes querying docstrings very easy.
In [1]: set?
Type: type
Base Class: <type 'type'>
String Form: <type 'set'>
Namespace: Python builtin
Docstring:
set(iterable) --> set object
Build an unordered collection.
It disappoints me when I have to go open the ElementTree documentation
instead of querying the methods themselves.
--
Robert Kern
rkern at ucsd.edu
"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4