At 10:55 AM 6/11/03 -0400, Guido van Rossum wrote: >[Phillip Eby] > > So, what I want to know is: > > > > * Do other people find pydoc inadequate? > >That's way too strong. It still does very well for the intended >purpose, which is to extracts docs out of typical library modules. It >may do poorly on funny things like descriptors and metaclasses, but >esoterica is not its primary goal. Fair enough. >Of course, it's annoying when pydoc raises an exception -- it would be >much better if it simply showed that some info was missing. > >In any case, in general I am in favor of a doc tool that scans source >code rather than doing introspection. There are cases where this >isn't right (e.g. when asking for help about a given object) but when >the object or module isn't already loaded, I think it's wrong to >import the module just to be able to extract its docs. I agree with you; my goal is to have tools that can do either, but share a common framework. Right now, the tools are split into mutually exclusive camps. > > * Does it seem likely that PyProtocols would be considered as an addition > > to the standard library (and by implication, used to document the > > interfaces of "standard" Python objects)? > >I have to admit that every time I try to read your docs, I glaze >over... Is there anything that you could suggest as to how I could improve that? In our previous discussions regarding the subject matter, you said that I made things sound too magical and easy, and I needed to document various things such as the requirements for protocol objects. So, I wrote the PyProtocols docs *very* specifically, in order to address your previous concern. That is, to show the "non-magicalness" of it. It sounds like perhaps I went too far to the other extreme. :) Anyway, it would be helpful if you (or anyone) could suggest ways to improve it. As I said, I'm seeking feedback, and that definitely includes constructive criticism. > Assuming it's yet another way of doing interfaces, I'm wary >of adopting *any* kind of standard approach until I've had much more >time to think over all the issues. I understand; you mentioned previously that you didn't want to take an approach that would exclude other approaches, so I made sure that PyProtocols interoperates "out of the box" with Twisted and Zope, to demonstrate that the approach doesn't require a single kind of interface. The docs also include examples of extending the provided protocol types to do other things. Thanks for the feedback and explaining your position. Now I can make more appropriate decisions about where and when to put my efforts.
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