[apug] Re: [Python-Dev] Call for clarity ( clarification ;-) )

[Hunter Peress]

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.
> 
>                        -- Mike
> 
> 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
> mgilfix@eecs.tufts.edu
> 
> For my gpg public key:
> http://www.eecs.tufts.edu/~mgilfix/contact.html"
>