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 > >
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4