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
