Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
[MRG+1] [DOC] Turn ginput dostring into a numpydocstring #8172
Conversation
dstansby
added the
Documentation
label
Feb 28, 2017
| + ---------- | ||
| + n : int, optional | ||
| + Number of mouse clicks to accumulate. If negative, accumulate | ||
| + clicks until the input is terminated manually. |
| - (or potentially both mouse buttons at once) terminates the input. | ||
| - | ||
| - Right clicking cancels last input. | ||
| + Blocking call to interact with a figure. This will wait for *n* |
anntzer
Feb 28, 2017
Contributor
I would rewrite the paragraph as
Wait until the user clicks n times on the figure. Returns the coordinates of each click in a list.
NelleV
Mar 2, 2017
Contributor
Also, I believe (though it is very unsure) that we decided to drop the "*", which are a remainer of the past in Matplotlib's documentation.
anntzer
Mar 2, 2017
Contributor
Not for arguments, see http://matplotlib.org/devdocs/devel/documenting_mpl.html#formatting.
| - (or potentially both mouse buttons at once) terminates the input. | ||
| - | ||
| - Right clicking cancels last input. | ||
| + Blocking call to interact with a figure. This will wait for *n* |
NelleV
Mar 2, 2017
Contributor
Also, I believe (though it is very unsure) that we decided to drop the "*", which are a remainer of the past in Matplotlib's documentation.
| + ---------- | ||
| + n : int, optional | ||
| + Number of mouse clicks to accumulate. If negative, accumulate | ||
| + clicks until the input is terminated manually. Default is 1. |
NelleV
Mar 2, 2017
Contributor
the numpydoc formats puts the default on the first line:
n : int, optional, default: 1
I find the numpydoc "offical" version more readable.
| + Returns | ||
| + ------- | ||
| + points : list of tuples | ||
| + The clicked points. ``len(points)`` will equal the number of points |
anntzer
Mar 2, 2017
Contributor
I would rewrite the entire thing (the three sentences) as A list of (x, y) coordinates of the clicks. There is no "number of requested points" if n<0, and there can be fewer points if the user presses mouse_stop prematurely.
| - (or potentially both mouse buttons at once) terminates the input. | ||
| - | ||
| - Right clicking cancels last input. | ||
| + Blocking call to interact with a figure. Wait until the user clicks *n* |
QuLogic
Mar 2, 2017
Member
The first line should be by itself with the remaining description on another paragraph (one blank line later).
| + Number of seconds to wait before timing out. If zero or negative | ||
| + will never timeout. | ||
| + show_clicks : bool, optional, default: False | ||
| + If True, show a red cross at the location of each click |
anntzer
Mar 2, 2017
Contributor
Add final dots here and below (including returns), and squash? (otherwise that's a lot of commits :-))
phobson
Mar 3, 2017
Member
In addition to the comment above, I think the format should be, for example
show_clicks : bool, optional (default = False)
anntzer
Mar 5, 2017
Contributor
@QuLogic I will approve the PR after this (the dots -- squashing is up to you) is fixed.
anntzer
Mar 6, 2017
Contributor
The format for defaults should probably added to the documenting matplotlib developer's guide. Note that numpy itself gives the example
Description of parameter `x` (the default is -1, which implies summation
over all axes).
(which is different and I dislike)
QuLogic
Mar 6, 2017
Member
I think you meant to tag @dstansby there; I'm fine with this when you are.
| + Number of seconds to wait before timing out. If zero or negative | ||
| + will never timeout. | ||
| + show_clicks : bool, optional, default: False | ||
| + If True, show a red cross at the location of each click |
anntzer
Mar 5, 2017
Contributor
@QuLogic I will approve the PR after this (the dots -- squashing is up to you) is fixed.
anntzer
referenced
this pull request
Mar 6, 2017
Closed
[MRG+1] FIX: eventplot 'colors' kwarg (#8193) #8204
dstansby
changed the title from
Turn ginput dostring into a numpydocstring to [DOC] Turn ginput dostring into a numpydocstring
Mar 7, 2017
|
I've added in the extra full stops, and given it a squash. |
anntzer
changed the title from
[DOC] Turn ginput dostring into a numpydocstring to [MRG+1] [DOC] Turn ginput dostring into a numpydocstring
Mar 7, 2017
NelleV
merged commit 8277ddf
into matplotlib:master
Mar 8, 2017
3 of 5 checks passed
|
Thanks @dstansby ! |
dstansby commentedFeb 28, 2017
No description provided.