[DOC] Slightly improve the LineCollection docstring #26676
Conversation
|
|
||
| or the equivalent numpy array with two columns. Each line | ||
| or the equivalent Mx2 numpy array with two columns. Each line |
There was a problem hiding this comment.
(M, 2)
I would perhaps completely drop the "list of points" and just write
A sequence ``[line0, line1, ...]`` where each line is a (N, 2)-shape
array-like of points::
line0 = [(x0, y0), (x1, y1), ...]
Each line can...
There was a problem hiding this comment.
I don't really care. This is a very quick PR to improve a misunderstanding in #26676. I have no time to bike shed this further. Feel free to push to this PR or take over if you think it's possible/worth improving further.
We can always write a 3D docstring, can't we? |
Yes. And thinking again, maybe that'd be the sane thing to do, even though that means writing an empty Anybody, this PR is just a quick fix for a misleading wording in LineCollection. I'm not going to bike shed this furher or add the 3D docstring. IMHO this can go in as-is as an improvement. Please take over for further improvements. |
…676-on-v3.8.x Backport PR #26676 on branch v3.8.x ([DOC] Slightly improve the LineCollection docstring)
PR summary
Closes #26674. There's two aspects to the issue:
the
LineCollectiondescription is slightly unclear. - This is fixed here.Line3DCollectioninherits__init__and reuses its docstring. That's problematic because the the description is 2D. I don't see a good solution here. We likely don't want to replicate the whole docstring, and also a comment like "This holds analogously for 3D with points (x0, y0, z0) and Mx3 arrays." is awkward both for the 2D and 3D docstrings.I therefore propose to leave it at this. If the 2D description is clear, the extension to 3D can be inferred by the user. - Not ideal, but the least bad option IMHO.