Steve Holden wrote: > In this particular case the documentation is quite explicit about the > return value and the documentation for the function runs to almost 400 > words. Do you expect *everything* to be in the source? That isn't > practical, as documenting everything twice like that makes twice the > work when the function changes and the documentation has to be rewritten.
(starting a new thread so that we're not off topic for the original one) Hmmm. Jerry Hill pointed out also that this information is documented clearly in the online docs (as opposed to docstrings I was looking at with pydoc). I guess I'm just confused about the purpose of pydoc and module documentation. I was under the impression it was intended to serve as the API reference, so when people say "consult the documentation" I usually check pydoc first before hitting the web browser. I was under the impression earlier that docs.python.org was mostly generated from the docstrings similar to how javadocs are converted to html. That being said, it does make sense to me however that you should be able to use pydoc to tell you simple things like the return value of a function, the required parameters, etc. I'd be interested to hear from some more experienced programmers what your typical usage would be when reference documentation for a given module. Are the HTML docs (e.g. what's on http://docs.python.org/) the canonical source? Is that where I should generally be looking? Are there other documentation resources you all have found useful as well? I'm curious to see if there are useful resources I'm just missing due to lack of knowledge or experience. Thanks, -Jay -- http://mail.python.org/mailman/listinfo/python-list
