Re: [Numpy-discussion] docstring suggestions
On Feb 12, 2010, at 11:01 PM, David Goldsmith wrote: On Fri, Feb 12, 2010 at 7:09 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 12, 2010, at 8:14 PM, David Goldsmith wrote Is the present issue an instance where Scott's second statement is invalid, an instance where its validity is resulting in a poor docstring for the function, or an instance in which Scott's recommendation was not followed? The methods' docstring are fine, but we could improve the way the corresponding function docstrings are created. Does anyone have an idea of how universal of a problem this is (i.e., is it just confined to ma)? Likely to be just a numpy.ma issue. I'll try to find some kind of fix. ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Sat, Feb 13, 2010 at 7:31 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 12, 2010, at 11:01 PM, David Goldsmith wrote: On Fri, Feb 12, 2010 at 7:09 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 12, 2010, at 8:14 PM, David Goldsmith wrote Is the present issue an instance where Scott's second statement is invalid, an instance where its validity is resulting in a poor docstring for the function, or an instance in which Scott's recommendation was not followed? The methods' docstring are fine, but we could improve the way the corresponding function docstrings are created. Does anyone have an idea of how universal of a problem this is (i.e., is it just confined to ma)? Likely to be just a numpy.ma issue. I'll try to find some kind of fix. Please don't misinterpret my statements to mean that I think this isn't important and/or that you should feel solely responsible for a fix - I sincerely just wanted to uncover the nature and extent of the problem. Unfortunately, I still feel like I don't really understand the functional origin of the problem, otherwise I'd be the first to be offering to help - perhaps if you can explain to me what you think is happening... DG ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Sat, Feb 13, 2010 at 9:53 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 13, 2010, at 11:56 PM, David Goldsmith wrote: Please don't misinterpret my statements to mean that I think this isn't important and/or that you should feel solely responsible for a fix - I sincerely just wanted to uncover the nature and extent of the problem. Unfortunately, I still feel like I don't really understand the functional origin of the problem, otherwise I'd be the first to be offering to help - perhaps if you can explain to me what you think is happening... In a nutshell: some functions in numpy.ma (like np.ma.compress) are actually instances of a factory class (_frommethod). This class implements a __call__ method, so its instances behave like functions. In practice, they just call a method of MaskedArray. Anyway, the __doc__ of the instance is created from the docstring of the corresponding method with _frommethod.getdoc. I'm sure that's where we can improve things (like substistute `self `by `a`. Because it's an instance, help(numpy.ma.compress) gives the docstring of numpy.ma._frommethod instead. In IPython, numpy.ma.compress? gives you the doc, twice (I don't get why). Excellent, thanks Pierre: w/ this in the thread, if I can't help (I'm no expert on factory classes, nor, certainly, on the why's and wherefore's of iPython) I'm all but certain we have the communal know-how to get this taken care of quickly. One final request, though, if I may: perhaps you could make the issue official by filing a ticket? Thanks again! DG PS: I can certainly take a look at _frommethod.getdoc and see what I can do with that... ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Feb 14, 2010, at 1:42 AM, David Goldsmith wrote: On Sat, Feb 13, 2010 at 9:53 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 13, 2010, at 11:56 PM, David Goldsmith wrote: Please don't misinterpret my statements to mean that I think this isn't important and/or that you should feel solely responsible for a fix - I sincerely just wanted to uncover the nature and extent of the problem. Unfortunately, I still feel like I don't really understand the functional origin of the problem, otherwise I'd be the first to be offering to help - perhaps if you can explain to me what you think is happening... In a nutshell: some functions in numpy.ma (like np.ma.compress) are actually instances of a factory class (_frommethod). This class implements a __call__ method, so its instances behave like functions. In practice, they just call a method of MaskedArray. Anyway, the __doc__ of the instance is created from the docstring of the corresponding method with _frommethod.getdoc. I'm sure that's where we can improve things (like substistute `self `by `a`. Because it's an instance, help(numpy.ma.compress) gives the docstring of numpy.ma._frommethod instead. In IPython, numpy.ma.compress? gives you the doc, twice (I don't get why). Excellent, thanks Pierre: w/ this in the thread, if I can't help (I'm no expert on factory classes, nor, certainly, on the why's and wherefore's of iPython) I'm all but certain we have the communal know-how to get this taken care of quickly. One final request, though, if I may: perhaps you could make the issue official by filing a ticket? Thanks again! Well, you're the one who started the conversation, so *you* should open the ticket ;) ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Sun, Feb 14, 2010 at 12:53 AM, Pierre GM pgmdevl...@gmail.com wrote: In IPython, numpy.ma.compress? gives you the doc, twice (I don't get why). I don't have a clue either, but it's now tracked at least: https://bugs.launchpad.net/ipython/+bug/521612 Thanks! f ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Sat, Feb 13, 2010 at 10:52 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 14, 2010, at 1:42 AM, David Goldsmith wrote: On Sat, Feb 13, 2010 at 9:53 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 13, 2010, at 11:56 PM, David Goldsmith wrote: Please don't misinterpret my statements to mean that I think this isn't important and/or that you should feel solely responsible for a fix - I sincerely just wanted to uncover the nature and extent of the problem. Unfortunately, I still feel like I don't really understand the functional origin of the problem, otherwise I'd be the first to be offering to help - perhaps if you can explain to me what you think is happening... In a nutshell: some functions in numpy.ma (like np.ma.compress) are actually instances of a factory class (_frommethod). This class implements a __call__ method, so its instances behave like functions. In practice, they just call a method of MaskedArray. Anyway, the __doc__ of the instance is created from the docstring of the corresponding method with _frommethod.getdoc. I'm sure that's where we can improve things (like substistute `self `by `a`. Because it's an instance, help(numpy.ma.compress) gives the docstring of numpy.ma._frommethod instead. In IPython, numpy.ma.compress? gives you the doc, twice (I don't get why). Excellent, thanks Pierre: w/ this in the thread, if I can't help (I'm no expert on factory classes, nor, certainly, on the why's and wherefore's of iPython) I'm all but certain we have the communal know-how to get this taken care of quickly. One final request, though, if I may: perhaps you could make the issue official by filing a ticket? Thanks again! Well, you're the one who started the conversation, so *you* should open the ticket ;) Actually, it was Hans Meine, but no matter, I'll file the __doc__ of the instance is created from the docstring of the corresponding method with _frommethod.getdoc. I'm sure that's where we can improve things (like substistute `self `by `a` and the Because it's an instance, help(numpy.ma.compress) gives the docstring of numpy.ma._frommethod instead as numpy tickets (I just thought you might be able to describe the problems better, and, due to a deeper understanding, be a better point of contact for the tickets - all I'll do is quote your above characterizations). Thanks, Fernando, for filing the iPython issue. DG Thanks, Fernando ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Friday 12 February 2010 13:43:56 Hans Meine wrote:
I was just looking for numpy.ma.compressed, but forgot its name.
Another strange thing is the docstring of numpy.ma.compress, which appears in
ipython like this:
Type: instance
Base Class: numpy.ma.core._frommethod
[...]
Docstring:
compress(self, condition, axis=None, out=None)
Return `a` where condition is ``True``.
[...]
Parameters
--
condition : var
[...]
axis : {None, int}, optional
[...]
out : {None, ndarray}, optional
[...]
Call def: numpy.ma.compress(self, a, *args, **params)
Note the `self` vs. `a` problem, as well as the call def which has both, but
no condition anymore. And `a`/self does not appear under parameters.
All these problems are probably related to numpy.ma.core._frommethod, but
anyhow this looks wrong from a user's POV.
HTH,
Hans
___
NumPy-Discussion mailing list
NumPy-Discussion@scipy.org
http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
2010/2/12 Hans Meine me...@informatik.uni-hamburg.de
On Friday 12 February 2010 13:43:56 Hans Meine wrote:
I was just looking for numpy.ma.compressed, but forgot its name.
Fixed this one in the Wiki.
Another strange thing is the docstring of numpy.ma.compress, which appears
in
ipython like this:
Type: instance
Base Class: numpy.ma.core._frommethod
[...]
Docstring:
compress(self, condition, axis=None, out=None)
Return `a` where condition is ``True``.
[...]
Parameters
--
condition : var
[...]
axis : {None, int}, optional
[...]
out : {None, ndarray}, optional
[...]
Call def: numpy.ma.compress(self, a, *args, **params)
Note the `self` vs. `a` problem, as well as the call def which has both,
but
no condition anymore. And `a`/self does not appear under parameters.
Uncertain how to fix this one - is it a bug in how the docstring is
interpreted somewhere along the line?
DG
PS: please, if you don't mind, in the future post docstring complaints at
scipy-dev (numpy-discussion has many more subscribers, many of whom probably
don't immediately care about any particular docstring problem, whereas
anyone who is working on the docstrings is - hopefully - subscribed to
scipy-dev); thanks.
All these problems are probably related to numpy.ma.core._frommethod, but
anyhow this looks wrong from a user's POV.
HTH,
Hans
___
NumPy-Discussion mailing list
NumPy-Discussion@scipy.org
http://mail.scipy.org/mailman/listinfo/numpy-discussion
___
NumPy-Discussion mailing list
NumPy-Discussion@scipy.org
http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? DG -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 14:26, David Goldsmith d.l.goldsm...@gmail.com wrote: On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? I don't see a reason to do that, either. -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 3:29 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:26, David Goldsmith d.l.goldsm...@gmail.com wrote: On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? I don't see a reason to do that, either. doceditor not moin Wiki, that was the policy that Ralf and David followed since last summer to have all docediting questions in one place. Josef -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 14:42, josef.p...@gmail.com wrote: On Fri, Feb 12, 2010 at 3:29 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:26, David Goldsmith d.l.goldsm...@gmail.com wrote: On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? I don't see a reason to do that, either. doceditor not moin Wiki, that was the policy that Ralf and David followed since last summer to have all docediting questions in one place. Is the volume of questions really so large to justify the inconvenience to the questioners? It's one thing to direct someone to, say, the matplotlib list when asking matplotlib questions, but no one is going to guess that they need to go to scipy-dev to ask a question about the doceditor when they run into a problem editing a numpy docstring. -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 3:47 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:42, josef.p...@gmail.com wrote: On Fri, Feb 12, 2010 at 3:29 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:26, David Goldsmith d.l.goldsm...@gmail.com wrote: On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? I don't see a reason to do that, either. doceditor not moin Wiki, that was the policy that Ralf and David followed since last summer to have all docediting questions in one place. Is the volume of questions really so large to justify the inconvenience to the questioners? It's one thing to direct someone to, say, the matplotlib list when asking matplotlib questions, but no one is going to guess that they need to go to scipy-dev to ask a question about the doceditor when they run into a problem editing a numpy docstring. No, I agree with you, short questions can be answered wherever they happen, especially if they are on topic. But, if it turns into a discussion about the internal structure of how doc strings are generated, then maybe David can redirect the traffic. Josef -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 14:58, josef.p...@gmail.com wrote: On Fri, Feb 12, 2010 at 3:47 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:42, josef.p...@gmail.com wrote: On Fri, Feb 12, 2010 at 3:29 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:26, David Goldsmith d.l.goldsm...@gmail.com wrote: On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? I don't see a reason to do that, either. doceditor not moin Wiki, that was the policy that Ralf and David followed since last summer to have all docediting questions in one place. Is the volume of questions really so large to justify the inconvenience to the questioners? It's one thing to direct someone to, say, the matplotlib list when asking matplotlib questions, but no one is going to guess that they need to go to scipy-dev to ask a question about the doceditor when they run into a problem editing a numpy docstring. No, I agree with you, short questions can be answered wherever they happen, especially if they are on topic. But, if it turns into a discussion about the internal structure of how doc strings are generated, then maybe David can redirect the traffic. I just don't see the reason for all that hassle, and it is a substantial hassle. You redirect people in order to get their question in front of the audience that can help them best or for truly off-topic discussions. As far as I'm concerned, questions about the doceditor, which drives the documentation for both numpy and scipy, are on-topic for any of either of the projects' lists. You don't redirect people just to keep things tidy. Mailing lists are messy things no matter what you do. -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
OK, OK, Ok, it's not worth getting into a flame war over. We ask people who are going to be working on the docstrings to subscribe to scipy-dev; this is not the same thing as being an innocent bystander asking a question or making a comment - I retract the request. Now, does anyone have anything useful to say about OP's original second problem? DG On Fri, Feb 12, 2010 at 1:05 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:58, josef.p...@gmail.com wrote: On Fri, Feb 12, 2010 at 3:47 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:42, josef.p...@gmail.com wrote: On Fri, Feb 12, 2010 at 3:29 PM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 14:26, David Goldsmith d.l.goldsm...@gmail.com wrote: On Fri, Feb 12, 2010 at 10:57 AM, Robert Kern robert.k...@gmail.com wrote: On Fri, Feb 12, 2010 at 12:19, David Goldsmith d.l.goldsm...@gmail.com wrote: PS: please, if you don't mind, in the future post docstring complaints at scipy-dev (numpy-discussion has many more subscribers, many of whom probably don't immediately care about any particular docstring problem, whereas anyone who is working on the docstrings is - hopefully - subscribed to scipy-dev); thanks. numpy docstrings get discussed on numpy-discussion. Then is it just the Wiki and related issues that we ask people to discuss @ scipy-dev? I don't see a reason to do that, either. doceditor not moin Wiki, that was the policy that Ralf and David followed since last summer to have all docediting questions in one place. Is the volume of questions really so large to justify the inconvenience to the questioners? It's one thing to direct someone to, say, the matplotlib list when asking matplotlib questions, but no one is going to guess that they need to go to scipy-dev to ask a question about the doceditor when they run into a problem editing a numpy docstring. No, I agree with you, short questions can be answered wherever they happen, especially if they are on topic. But, if it turns into a discussion about the internal structure of how doc strings are generated, then maybe David can redirect the traffic. I just don't see the reason for all that hassle, and it is a substantial hassle. You redirect people in order to get their question in front of the audience that can help them best or for truly off-topic discussions. As far as I'm concerned, questions about the doceditor, which drives the documentation for both numpy and scipy, are on-topic for any of either of the projects' lists. You don't redirect people just to keep things tidy. Mailing lists are messy things no matter what you do. -- 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://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Feb 12, 2010, at 4:24 PM, David Goldsmith wrote: OK, OK, Ok, it's not worth getting into a flame war over. We ask people who are going to be working on the docstrings to subscribe to scipy-dev; this is not the same thing as being an innocent bystander asking a question or making a comment - I retract the request. Now, does anyone have anything useful to say about OP's original second problem? Yes: write a proper docstring, or find me a better way to automatically create the docstring of a function from the docstring of the corresponding method (or vice-versa) than we have now for numpy.ma. I agree that the current method is not ideal, but at least you get some kind of info. ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 2:30 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 12, 2010, at 4:24 PM, David Goldsmith wrote: OK, OK, Ok, it's not worth getting into a flame war over. We ask people who are going to be working on the docstrings to subscribe to scipy-dev; this is not the same thing as being an innocent bystander asking a question or making a comment - I retract the request. Now, does anyone have anything useful to say about OP's original second problem? Yes: write a proper docstring, or find me a better way to automatically create the docstring of a function from the docstring of the corresponding method (or vice-versa) than we have now for numpy.ma. I agree that the current method is not ideal, but at least you get some kind of info. Ah, now I understand. We've been here before: http://docs.scipy.org/numpy/Questions+Answers/#documenting-equivalent-functions-and-methods No canonical answer has been recorded, but Scott Sinclair commented: In the the masked array module we should doc the methods. The functions automatically have the same docstring. Is the present issue an instance where Scott's second statement is invalid, an instance where its validity is resulting in a poor docstring for the function, or an instance in which Scott's recommendation was not followed? In any event, Ralf Gommers agreed w/ Scott's first statement, I'm neutral, and no one else appears to have voted... DG ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Feb 12, 2010, at 8:14 PM, David Goldsmith wrote Is the present issue an instance where Scott's second statement is invalid, an instance where its validity is resulting in a poor docstring for the function, or an instance in which Scott's recommendation was not followed? The methods' docstring are fine, but we could improve the way the corresponding function docstrings are created. ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] docstring suggestions
On Fri, Feb 12, 2010 at 7:09 PM, Pierre GM pgmdevl...@gmail.com wrote: On Feb 12, 2010, at 8:14 PM, David Goldsmith wrote Is the present issue an instance where Scott's second statement is invalid, an instance where its validity is resulting in a poor docstring for the function, or an instance in which Scott's recommendation was not followed? The methods' docstring are fine, but we could improve the way the corresponding function docstrings are created. Does anyone have an idea of how universal of a problem this is (i.e., is it just confined to ma)? Scott's statement appears to imply that he thought there was no problem at all. DG ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
