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
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.
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:
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.
For a ready example, imagine having a module that contains useful helper functions. How are you going to identify the type requirements of those functions if you don't have context? How can you be sure that you've convered all contexts (including conversions).
Such is the nature of dynamic languages. It's very hard to do what you'd like to do here.
On Sat, Sep 07 @ 21:22, Hunter Peress wrote:
I think its easier to enforce this from the level i describe, than have guido saying "ok guys please be more explicit in your documentation". I mean, both of those documents above are somewhat explicit, but they are not COMPLETE.
Could you provide me with some linkage on parsing python (from a compilation/ syntax-tree analysis POV). SO that i can get to work on writing a patch for the pydoc generation program.
-- Michael Gilfix firstname.lastname@example.org
For my gpg public key: http://www.eecs.tufts.edu/~mgilfix/contact.html"