Note: You additionally have to make the docstring a raw string r``` because of the plural s for .Artists.

Is this true though? While Collection inherits from Artist, it re-implements basically the entire Patch interface with plural method/property names. In addition, its properties default to patches. values from rc.

My impression from reading the code was that the only reason Collection doesn't inherit from Patch is because we wanted plural method names (but that might be an a posteriori justification, since I obviously wasn't around for the implementation).

The point is, while the Python Collection object is an artist, that part can be inferred from the class structure on the relevant docs page. The part that is not clear unless you literally read all the properties of Artist/Collection/Patch and compare them manually is that Collection semantically represents a collection of Patches to be drawn simultaneously (i.e. it has edgecolor, facecolor, etc.).

Also, I hesitate to remove the wording about "may be" more efficient, since for most renderers, draw_path_collection is not necessarily any more efficient than individual draw_path calls (it just typically is whenever Collections are used correctly).

But I do see why you wanted to change it, the wording is pretty awkward, so I'll try changing it.

You may be mostly right with Patch. I was thinking of LineCollection which rather mimics a list of Line2D and thus went for the more general Artist. This is all a bit messy.

Is it reasonable to stick to Patch and just mention in LineCollection that it's different?

Performance: I didn't check, but I assume the advantage of collections is that you save a lot of python function calls, similar to how numpy is faster than a list of floats.

I'll update the docs to refer to patch and make sure that LineCollection is clear about how it's basically the same thing but for Line2D.

I think you're right about the performance in theory, but in practice, backend base still breaks up draw_path_collection into individual draw_path calls anyway, so you don't gain performance unless the backend supports it, which was probably the justification for the original language.

Not sure if the backend is the bottleneck or creating the Artists, but in a quick test LineCollection is faster:

import matplotlib.pyplot as plt
from matplotlib.lines import Line2D
from matplotlib.collections import LineCollection
import numpy as np

xs = np.linspace(0, 1, 1000)

%%timeit
fig, ax = plt.subplots()
for x in xs:
    line = Line2D([x, x], [0, 1])
    ax.add_line(line)

445 ms ± 9.8 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

%%timeit
fig, ax = plt.subplots()

lc = LineCollection([[(x, 0), (x, 1)] for x in xs])
ax.add_collection(lc)

39.7 ms ± 1.13 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)

I think odd-length sequences are allowed, see #17444. Or is that specifically not supported in collections?

This was only written to match what is currently said in Line2D.set_dashes and Line2D.set_linestyle. I see that we now accept odd-length sequences in our backends, but all the user-facing documentation says otherwise. Are we sure that there's not other third-party backends that assume even length?

I'd personally prefer to make a separate PR fixing this since I'll want to fix it in 4-5 places throughout the documentation to more correctly describe how we do dashes...

EDIT: 12+ places where this needs changes. Would definitely prefer to do this in a separate PR.