Improve BezPath docs

[rylev]

The docs for BezPath's methods seem a bit too literal. For instance, curveto says "Push a curveto element onto the path." which is technically correct, but something like "appends a cubic Bézier curve to the path" might be more helpful. I found Apple's UIKit docs for this pretty nice: https://developer.apple.com/documentation/uikit/uibezierpath/1624357-addcurve

[raphlinus]

Yes, it's pretty basic right now and could definitely be improved. One question is whether the primary point of documentation for that should be the curveto method or the PathEl::Curveto enum. I think I'd lean toward the former, as it's more similar to the PostScript original model, and more likely to be the point of contact.

Another question: is it practical to include SVG in kurbo rustdoc? Math? I do both in my blog, and I'm ok with pushing the boundaries a bit here. If we can't do it in rustdoc, we should have a canonical place (maybe a docs subdir) where it is enabled.

[jrus]

I don’t know whether it’s directly relevant to this conversation, but personally I find it a lot nicer to directly manipulate some data structure listing control points or the like, and then pass it into a function that can draw the whole shape, rather than repeatedly calling .curveTo, .lineTo, etc.

Having the data stored as data instead of a black box that gets appended to bit by bit with a procedural API is more flexible to interact with from arbitrary styles of external code. But maybe less familiar to people used to existing 1980s style procedural APIs.

The existing APIs all sort of remind me of thinking of drawing using the Logo turtle, where the command syntax has a pedagogical purpose helping small children relate the code to performing a list of physical actions with their bodies, and there are even physical turtle robots that can move around and drag a pen around on the floor. The relative motion commands, the way the SVG spec keeps trying to cram in new path syntax without adding fundamentally different primitives, etc. all ends up just complicating the mental model of the user for little concrete benefit IMO.

A more data-centric modern-CPU/GPU friendly version is just a big 8-column array of control point values (or polynomial coefficients) for each cubic segment. If the last control point of one segment is (close enough to) equal to the first control point of the next segment, one is considered to follow the other. YMMV.