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

[Michael Gilfix]

  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 :)

  More below...


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 :)

                  -- Mike

-- 
Michael Gilfix
mgilfix@eecs.tufts.edu

For my gpg public key:
http://www.eecs.tufts.edu/~mgilfix/contact.html"