Re: [Numpy-discussion] Docstring standard: how to specify variable types
Hi Charles On Wed, Jan 23, 2008 at 09:34:44AM -0700, Charles R Harris wrote: 2. How do we specify default values? I like to put them first in the list: {-1, integer} When exactly is this list used? That should be made clear in the standard as well. 3. Why do we need the optional keyword (the function signature already indicates that the parameter is optional). It's extra information, true, but that isn't always a bad thing. It's like looking up whole numbers in a book index and, instead of the page reference, the index directs you to numbers, whole. Flip, flip, flip. Drives me crazy. Besides, the function signature might be missing. When would the function signature be missing? In C functions we copy the signature into the docstring. I am concerned about duplicating information that may change. 4. Do we really need the Other Parameters list? It would make more sense to split positional and keyword arguments, but I'm not even sure that is necessary, since that information is already specified in the function signature. I agree, but Travis likes this section and I don't feel strongly about it. If I understood its role properly, I would be happier to use it, but at the moment I'm not convinced that it contributes anything useful. Parameters are normally sorted from most to least valuable anyway. 5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a limited number of values? In Python {} is a dictionary, so why not use ('hi','ho') instead? Either would be fine. IIRC, the {} was inherited from epydoc consolidated fields. I thought that, since we threw all epydoc guidelines out the window, this would be a good time talk about it -- the next docday is just around the corner! Thank you very much for your response. Regards Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Docstring standard: how to specify variable types
Hi, When would the function signature be missing? In C functions we copy the signature into the docstring. I am concerned about duplicating information that may change. I guess that would be def my_func(*args, **kwargs): although, if you're going to document the parameters in detail for such a function, it seems sensible to specify what the args are in the signature. I thought that, since we threw all epydoc guidelines out the window, this would be a good time talk about it -- the next docday is just around the corner! Perhaps we could have that discussion on the IRC channel on Friday at some specified time? Matthew ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Docstring standard: how to specify variable types
Also, Perhaps we could have that discussion on the IRC channel on Friday at some specified time? I suppose it's possible to hack up some processor of the form: doc_me('my_file.py') that can introspect things like argument lists, add boilerplate and process the resulting text according to the given rules. And maybe switch between standards if we change. Matthew ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Docstring standard: how to specify variable types
Stefan van der Walt wrote: Hi Charles On Wed, Jan 23, 2008 at 09:34:44AM -0700, Charles R Harris wrote: 2. How do we specify default values? I like to put them first in the list: {-1, integer} When exactly is this list used? That should be made clear in the standard as well. No special processing is done. I omit it. If I need to talk about the default value, I do it in prose in the argument's description. Note that the default value is not always the same thing as the value in the signature, particularly when kwd=None. But in those cases, I usually need a sentence to describe what's happening, so that's where I always put that information. 3. Why do we need the optional keyword (the function signature already indicates that the parameter is optional). It's extra information, true, but that isn't always a bad thing. It's like looking up whole numbers in a book index and, instead of the page reference, the index directs you to numbers, whole. Flip, flip, flip. Drives me crazy. Besides, the function signature might be missing. When would the function signature be missing? In C functions we copy the signature into the docstring. I am concerned about duplicating information that may change. 4. Do we really need the Other Parameters list? It would make more sense to split positional and keyword arguments, but I'm not even sure that is necessary, since that information is already specified in the function signature. I agree, but Travis likes this section and I don't feel strongly about it. If I understood its role properly, I would be happier to use it, but at the moment I'm not convinced that it contributes anything useful. Parameters are normally sorted from most to least valuable anyway. Look at the scipy.optimize.fmin*() functions, for instance. If you don't feel like using it, don't. None of the numpy function signatures should be long enough to need it. 5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a limited number of values? In Python {} is a dictionary, so why not use ('hi','ho') instead? Either would be fine. IIRC, the {} was inherited from epydoc consolidated fields. I thought that, since we threw all epydoc guidelines out the window, this would be a good time talk about it -- the next docday is just around the corner! Personally, I don't think it's worth standardizing. If it's readable and valid reST, just do it. -- Robert Kern I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth. -- Umberto Eco ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Docstring standard: how to specify variable types
Hi Robert On Thu, Jan 24, 2008 at 01:15:13PM -0600, Robert Kern wrote: 5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a limited number of values? In Python {} is a dictionary, so why not use ('hi','ho') instead? Either would be fine. IIRC, the {} was inherited from epydoc consolidated fields. I thought that, since we threw all epydoc guidelines out the window, this would be a good time talk about it -- the next docday is just around the corner! Personally, I don't think it's worth standardizing. If it's readable and valid reST, just do it. The attached output shows the difference between using {} and () -- it doesn't seem to make a difference. Since [] or () is normally used to indicate a set, I found it more natural. Either way, I think I'll follow your other suggestion and not use such a list -- rather specify the default value in the prose. Thanks Stéfan Title: ReST lists test ReST lists test Two different ways of specifying parameter lists. Parameters a : {1, sometype, sometype2} This is some keyword description. b : (2, sometype, sometype3) And so is this. c : 3, why, have, brackets, at, all Another keyword prose. Default: 3. ReST text: ReST lists test === Two different ways of specifying parameter lists. Parameters -- a : {1, sometype, sometype2} This is some keyword description. b : (2, sometype, sometype3) And so is this. c : 3, why, have, brackets, at, all Another keyword prose. Default: 3. ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Docstring standard: how to specify variable types
On Jan 24, 2008 1:53 PM, Stefan van der Walt [EMAIL PROTECTED] wrote: Hi Robert On Thu, Jan 24, 2008 at 01:15:13PM -0600, Robert Kern wrote: 5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a limited number of values? In Python {} is a dictionary, so why not use ('hi','ho') instead? Either would be fine. IIRC, the {} was inherited from epydoc consolidated fields. I thought that, since we threw all epydoc guidelines out the window, this would be a good time talk about it -- the next docday is just around the corner! Personally, I don't think it's worth standardizing. If it's readable and valid reST, just do it. The attached output shows the difference between using {} and () -- it doesn't seem to make a difference. Since [] or () is normally used to indicate a set, I found it more natural. I think it best for everyone to settle on one or the other, both for consistency of appearance and later convenience if someone wants to parse the documentation. Using neither {} nor () looks would also be reasonable, but why don't we just go with the current standard? It was a bit of a surprise to me, too. But *having* a working standard is more important than the details. In the end, these things are just useful conventions. Sets are normally defined using {} these days and set union and difference are no longer '+' and '-'. There are old books where Euler angles are defined using left handed coordinate systems. The Russian literature used '+' instead of '-' as the sign in the exponential of the forward Fourier transform. Strangest of all, in tensor analysis the meanings of covariant and contravariant are interchanged. So all of those things could have gone differently. Chuck ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] Docstring standard: how to specify variable types
Hi all, The numpy documentation standard example shows: Parameters -- var1 : array_like Array_like means all those objects -- lists, nested lists, etc. -- that can be converted to an array. var2 : integer Write out the full type long_variable_name : {'hi', 'ho'}, optional Choices in brackets, default first when optional. I'd like to know: 1. array_like describes objects that can be forced to quack like ndarrays. Are there any other such special descriptions? 2. How do we specify default values? 3. Why do we need the optional keyword (the function signature already indicates that the parameter is optional). 4. Do we really need the Other Parameters list? It would make more sense to split positional and keyword arguments, but I'm not even sure that is necessary, since that information is already specified in the function signature. 5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a limited number of values? In Python {} is a dictionary, so why not use ('hi','ho') instead? Thanks for your feedback! Regards Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Docstring standard: how to specify variable types
On Jan 23, 2008 6:55 AM, Stefan van der Walt [EMAIL PROTECTED] wrote: Hi all, The numpy documentation standard example shows: Parameters -- var1 : array_like Array_like means all those objects -- lists, nested lists, etc. -- that can be converted to an array. var2 : integer Write out the full type long_variable_name : {'hi', 'ho'}, optional Choices in brackets, default first when optional. I'd like to know: 1. array_like describes objects that can be forced to quack like ndarrays. Are there any other such special descriptions? I can't think of any, but that doesn't mean there aren't any. 2. How do we specify default values? I like to put them first in the list: {-1, integer} 3. Why do we need the optional keyword (the function signature already indicates that the parameter is optional). It's extra information, true, but that isn't always a bad thing. It's like looking up whole numbers in a book index and, instead of the page reference, the index directs you to numbers, whole. Flip, flip, flip. Drives me crazy. Besides, the function signature might be missing. 4. Do we really need the Other Parameters list? It would make more sense to split positional and keyword arguments, but I'm not even sure that is necessary, since that information is already specified in the function signature. I agree, but Travis likes this section and I don't feel strongly about it. 5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a limited number of values? In Python {} is a dictionary, so why not use ('hi','ho') instead? Either would be fine. IIRC, the {} was inherited from epydoc consolidated fields. Chuck ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion