[Numpy-discussion] Why are ufunc docstrings useless?
Hi, I frequently use functions like np.add.reduce and np.add.outer, but their docstrings are totally uninformative. Would it be possible to provide proper docstrings for these ufunc methods? They need not be specific to np.add; just an explanation of what arguments to give (for example) reduce() (presumably it takes an axis= argument? what is the default behaviour?) and what it does would help. Thanks, Anne ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 5:28 PM, Anne Archibald [EMAIL PROTECTED] wrote: Hi, I frequently use functions like np.add.reduce and np.add.outer, but their docstrings are totally uninformative. Would it be possible to provide proper docstrings for these ufunc methods? They need not be specific to np.add; just an explanation of what arguments to give (for example) reduce() (presumably it takes an axis= argument? what is the default behaviour?) and what it does would help. Sure. The place to add them would be in the PyMethodDef ufunc_methods array on line 3953 of numpy/core/src/ufuncobject.c. Just extend each of the rows with a char* containing the docstring contents. A literal string will suffice. -- 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] Why are ufunc docstrings useless?
2008/5/8 Robert Kern [EMAIL PROTECTED]: On Thu, May 8, 2008 at 5:28 PM, Anne Archibald [EMAIL PROTECTED] wrote: Hi, I frequently use functions like np.add.reduce and np.add.outer, but their docstrings are totally uninformative. Would it be possible to provide proper docstrings for these ufunc methods? They need not be specific to np.add; just an explanation of what arguments to give (for example) reduce() (presumably it takes an axis= argument? what is the default behaviour?) and what it does would help. Sure. The place to add them would be in the PyMethodDef ufunc_methods array on line 3953 of numpy/core/src/ufuncobject.c. Just extend each of the rows with a char* containing the docstring contents. A literal string will suffice. Thanks! Done add, reduce, outer, and reduceat. What about __call__? Anne ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 9:52 PM, Anne Archibald [EMAIL PROTECTED] wrote: Thanks! Done add, reduce, outer, and reduceat. What about __call__? If anyone knows enough to explicitly request a docstring from __call__, they already know what it does. -- 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] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 9:07 PM, Robert Kern [EMAIL PROTECTED] wrote:
On Thu, May 8, 2008 at 9:52 PM, Anne Archibald
[EMAIL PROTECTED] wrote:
Thanks! Done add, reduce, outer, and reduceat. What about __call__?
If anyone knows enough to explicitly request a docstring from
__call__, they already know what it does.
--
It's easier/better to do this in numpy/add_newdocs.py. For example:
In [14]: from numpy.lib import add_newdoc as add
In [15]: add('numpy.core','ufunc',('reduce','hello world'))
In [16]: ufunc.reduce.__doc__
Out[16]: 'hello world'
You don't have to clutter up the c sources and you can use , instead
of putting all those newlines in.
Chuck
___
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 10:12 PM, Charles R Harris
[EMAIL PROTECTED] wrote:
It's easier/better to do this in numpy/add_newdocs.py. For example:
In [14]: from numpy.lib import add_newdoc as add
In [15]: add('numpy.core','ufunc',('reduce','hello world'))
In [16]: ufunc.reduce.__doc__
Out[16]: 'hello world'
You don't have to clutter up the c sources and you can use , instead
of putting all those newlines in.
Ah good. I didn't realize it would handle builtin type methods.
--
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] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 9:12 PM, Charles R Harris [EMAIL PROTECTED]
wrote:
On Thu, May 8, 2008 at 9:07 PM, Robert Kern [EMAIL PROTECTED] wrote:
On Thu, May 8, 2008 at 9:52 PM, Anne Archibald
[EMAIL PROTECTED] wrote:
Thanks! Done add, reduce, outer, and reduceat. What about __call__?
If anyone knows enough to explicitly request a docstring from
__call__, they already know what it does.
--
It's easier/better to do this in numpy/add_newdocs.py. For example:
In [14]: from numpy.lib import add_newdoc as add
In [15]: add('numpy.core','ufunc',('reduce','hello world'))
In [16]: ufunc.reduce.__doc__
Out[16]: 'hello world'
You don't have to clutter up the c sources and you can use , instead
of putting all those newlines in.
Also, not all c compilers will join strings on separate lines. You need to
add explicit continuation backslashes.
Chuck
___
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Why are ufunc docstrings useless?
2008/5/8 Robert Kern [EMAIL PROTECTED]: On Thu, May 8, 2008 at 9:52 PM, Anne Archibald [EMAIL PROTECTED] wrote: Thanks! Done add, reduce, outer, and reduceat. What about __call__? If anyone knows enough to explicitly request a docstring from __call__, they already know what it does. How exactly are they to find out? It does take additional arguments, for example dtype and out - I think. Also, help(np.add) displays the the object, its docstring, its methods, and all their docstrings. So it provides a way to get a docstring out of __call__ without having to know what it is. Anne ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 10:39 PM, Anne Archibald [EMAIL PROTECTED] wrote: 2008/5/8 Robert Kern [EMAIL PROTECTED]: On Thu, May 8, 2008 at 9:52 PM, Anne Archibald [EMAIL PROTECTED] wrote: Thanks! Done add, reduce, outer, and reduceat. What about __call__? If anyone knows enough to explicitly request a docstring from __call__, they already know what it does. How exactly are they to find out? It does take additional arguments, for example dtype and out - I think. That should be recorded in the ufunc's main docstring, e.g. numpy.add.__doc__, since that is what people will actually be calling. No one will explicitly call numpy.add.__call__(x,y). Also, help(np.add) displays the the object, its docstring, its methods, and all their docstrings. So it provides a way to get a docstring out of __call__ without having to know what it is. Meh. All it can usefully say is Refer to the main docstring. Which is more or less what it currently says. -- 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] Why are ufunc docstrings useless?
2008/5/8 Robert Kern [EMAIL PROTECTED]: On Thu, May 8, 2008 at 10:39 PM, Anne Archibald [EMAIL PROTECTED] wrote: 2008/5/8 Robert Kern [EMAIL PROTECTED]: If anyone knows enough to explicitly request a docstring from __call__, they already know what it does. How exactly are they to find out? It does take additional arguments, for example dtype and out - I think. That should be recorded in the ufunc's main docstring, e.g. numpy.add.__doc__, since that is what people will actually be calling. No one will explicitly call numpy.add.__call__(x,y). Also, help(np.add) displays the the object, its docstring, its methods, and all their docstrings. So it provides a way to get a docstring out of __call__ without having to know what it is. Meh. All it can usefully say is Refer to the main docstring. Which is more or less what it currently says. So is the custom that double-underscore methods get documented in the class docstring and normal methods get documented in their own docstrings? Anne ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Why are ufunc docstrings useless?
On Thu, May 8, 2008 at 11:31 PM, Anne Archibald [EMAIL PROTECTED] wrote: 2008/5/8 Robert Kern [EMAIL PROTECTED]: On Thu, May 8, 2008 at 10:39 PM, Anne Archibald [EMAIL PROTECTED] wrote: 2008/5/8 Robert Kern [EMAIL PROTECTED]: If anyone knows enough to explicitly request a docstring from __call__, they already know what it does. How exactly are they to find out? It does take additional arguments, for example dtype and out - I think. That should be recorded in the ufunc's main docstring, e.g. numpy.add.__doc__, since that is what people will actually be calling. No one will explicitly call numpy.add.__call__(x,y). Also, help(np.add) displays the the object, its docstring, its methods, and all their docstrings. So it provides a way to get a docstring out of __call__ without having to know what it is. Meh. All it can usefully say is Refer to the main docstring. Which is more or less what it currently says. So is the custom that double-underscore methods get documented in the class docstring and normal methods get documented in their own docstrings? No. Objects whose main purpose is to be callable should document their call signature in the main docstring since that's where the objects they are mimiccing (functions) have their docstring. In this case, there is also a technical reason: you can't override add.__call__.__doc__, just ufunc.__call__.__doc__, but the call signatures vary between ufuncs. -- 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
