Edit docs for pixels functions

[nickmcintyre]

Addresses #6389

Changes:

I edited the inline documentation and code samples for image functions under the "Pixels" subheading.

@stalgiag @cgusb @photon-niko @KleoP @davepagurek @Qianqianye I'd love to incorporate any feedback you may have. Here's a staging version of the proposed changes for your convenience.

PR Checklist

• npm run lint passes
• [Inline documentation] is included / updated

[davepagurek]

Looking great so far, thanks for your work on this @nickmcintyre! I suggested a few spots where we could add a bit more info, let me know if it's trying to add too much / just adding clutter though!

[davepagurek]

This wasn't in the previous version either, but I think the main qualifier here is to use pixels if you're going to read a bunch of pixels, but for just one, get() is fine and probably a bit faster. Maybe we could add something like "if many pixels will be read" to the next end?

[nickmcintyre]

Good suggestion. Added this wording to get() and set().

[davepagurek]

Probably worth noting that this version returns it as a p5.Image instead of an array, so it can be used with image(...) or img.filter(...).

[nickmcintyre]

Agreed, done!

[davepagurek]

This method is also available on p5.Graphics, but I'm not sure we have separate docs for that or mention it anywhere. Is it worth mentioning that here too, if we're already mentioning how something similar exists on p5.Image?

[nickmcintyre]

This one's tough. It looks like those docs are part of p5.Renderer2D which aren't displayed on the site. Referencing the p5.Graphics.get() without a link or the invisible p5.Renderer2D.get() both seem less than ideal.

[davepagurek]

Ah, yeah good point. Probably not something to address in this issue then, but for longer term changes, what do you feel would be the best way to manage this sort of thing? Some docs pages mention when classes extend other classes and have a link to the super class docs page under the list of methods, but class hierarchy might be kind of confusing to newcomers. We could maybe list every method, including inherited ones? (Ideally in an automated way to avoid copy-and-pasting docs, where copies could go out of date?)

[nickmcintyre]

Oops, I just reread the source and found where p5.Graphics binds methods from the p5 instance that's passed during construction. Now I get that p5.Graphics objects arise from a flavor of multiple inheritance with p5 and p5.Element. That's way too complex for newcomers.

I like your idea to automatically include documentation from super classes. Agreed it's helpful for completeness and maintainability with subclasses. For p5.Graphics specifically, I think it's worth emphasizing and revising that "The fields and methods for this class are extensive, but mirror the normal drawing API for p5."

[davepagurek]

Great work on this!

[nickmcintyre]

Thanks, and thanks for your feedback @davepagurek!