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

[Hunter Peress]

Ok heres some more detail.

I have no idea how pydoc works right now. I assume you call some program
on a python file, and it simply looks for all """   """.

It seems to do SOME lexical/scoping analysis of where to look for """
""", and consequently, how to display that information in the final,doc
form; but I'm asking for more.

As I said, python methods/functions are not explcitely typed. So what I
propose is this:

When the pydoc generator comes accross a function/method, there should
remain a normal """ """ area for any comments. I'm asking now, that when
the generator sees its in a method/function, it does a NEW check for a
set of docs that document the type of each input argument, and the
output.

EG (theoretical, and off the top of my head):

in a file you have a function:

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"""    #documents the type of the first arg
   """string"""  #              ""          second 
   """list"""    #              ""          third
   """string"""  #documents the return type.

Then the pydoc generator will do a check on the #  arguments to the
func/meth, verify that the correct amount of these new comments (which
only supply the type) are provided. I do think that it would help to
actually enforce this. I think its fine that doc's NOT be generated if
they don't supply this information. This provides for better docs and
shouldnt get that many complaints. 

Then: If the docs are generated into webpages, links to the known types
that are checked are provided. And if the docs are going into shell
format then i dont know if links are necessary.

There are lots of cases and issues that I havent discussed for this
proposed implemenation. So I would like to continue this thread for the
purposes of detailing this idea further.

> > This could clear up a lot of confusion and further python's
> > effectiveness.
As we know, python is not an explicitely typed language, but enforcing
some level of typing at the documentation level will see a lot of people
falling into line (depending on how rigidly its enforced, and i do
suggest a pretty rigid level).


I have no patch ATM because I tend to design software before writing it,
and im looking for support from the developers first.

PS whats TIA mean?
 
On Wed, 2002-09-04 at 17:56, Martin v. Loewis wrote:
> Hunter Peress <hu.peress@mail.mcgill.ca> writes:
> 
> > This could clear up a lot of confusion and further python's
> > effectiveness.
> 
> It's not clear, to me, from reading your message, what kind of change
> you are requesting (that you are requesting a change, rather than
> offering help, or asking for advice, appears to be clear).
> 
> Could you kindly provide a small patch that gives an idea of what you
> would like to see changed, and how?
> 
> TIA,
> Martin
> 
>