Ok. I think I understand better what you're trying to accomplish. I got the impression earlier (and I think others did as well) that you were hoping to have pydoc automatically label types on the function call. A new convention might very well be welcomed. You might want to post a couple of examples and the corresponding documentation for feedback here before you start the hard work on the patch :)
On Sun, Sep 08 @ 02:11, Hunter Peress wrote:
Actually all of the thinking i did WAS taking into account the "dynamic" nature of python.
But its not like the actual code is being rewritten fast enough to make this unfeasible or unneccesary.
Im glad to get all of this feedback as its helping me formulate, and further specify my plans (or eventually healthily debunk them (as the past 3 responders have helped do)).
Instead of just thinking:
"arguments are not explicitely anything, therefore it makes no sense to even attempt to document them explicitely".
I think this: simply add the capability for multiple definitions per each argument. eg going back to my original sample here is an updated version:
def something(a,b,c="lalal"): """This will find its way into the pydocs because its a comment""" ##Here is the new stuff Im proposing ##note, a clearer sytnax can surely be devised. """file,socket""" #documents the type(s) of the first arg """string,list""" # "" second """list,hash""" # "" third """string,hash""" #documents the return type(s).
Thats quite a simple solution, and still provides worlds better exactness and clarity than the current system allows.
Onto more of your concerns: On Wed, 2002-09-04 at 23:45, Michael Gilfix wrote:
While I understand what you're trying to do here (and think it would be quite nice), I'm not sure how you're going to accomplish it. How will parsing python using a syntax-tree help? It's not going to tell you what the function does in all cases or the various types it could handle.Perhaps you could make educated guesses by looking at the types of operations on the objects (a 'has_key' is a sure indicator of a hash), but that would be sketchy at best.
Actually I wasnt suggesting this AT ALL wrt intelligent guesses, and for now this proposal leans away from it.
Rather there are only 2 simple things that I wanted to obtain from the parse-tree: the number of arguments, and if possible to see if there
Agreed now that things are clearer.
Assume for now that my whole proposal will simply be another option (instead of the default) to the pydoc-generator program. If invoked, it will fail (if the super strict option is specified) if you don't supply definitions for number of args for a given method.
This brings up your "dynamic" language issue again.
When u have lots of args being used as different things, my program then introduces another level of complexity to deciphering the docs in a meaningful way.
Eg: a sample output of this program based on my example:
------------output----------------- method: something(a (file,socket),b (string,list),c="lalal" (list,hash)) return type :string,hash
This will find its way into the pydocs because its a comment
Now in html format it would be even nicer as there will be links to the types listed.
I agree. I know that I'd welcome an extra added option to enable some extra pydoc functionality. Developing a schema is tricky though and you should probably engage in some more debate first :)
And now looking at it, I think its much clearer than nothing at al.
Of course there is going to be that type of code where u have no need of documenting every method because their names are self explantory, and such explicit documentation isnt necessary, thats not what this is really intended for.
If the specific argument arises that "since python is a dynamic language your approach doesnt make sense" say, then I have to respond:
Of course it applies. Because of my misunderstanding, I was under the impression that you wanted to generate the equivalent of function calls, not develop a scheme like javadoc. The dynamic nature of Python means that such specifications become even more important as project sizes increase.
an attempt at specifiying things is FAR better than nothing, and moreover, this is only my first attempt. Allowing it to become a part of the generator as an option will open it up to user input, and hence improvement, AND!
it might just turn out that a "dynamic" approach will be necessary to document a "dynamic" language.
So im still looking for more design tips, and a place where I could find out how to get into the meat of the python parser, but i think the "http://python.org/doc/2.2/lib/module-parser.html" is probably what I'll be using.
Shouldn't there be code in the existing pydoc to do much of what you want for you? It seems like it might be nice to re-engineer pydoc to take some handlers that allow you to do further customization after it's done it's thing. That way, we can add extensions into the existing code and all that integration stuff might be a little easier.
Good luck n' keep us posted :)