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