Expand documentation with additional examples of how API can be used

[oskay]

Please explain how one would use the API to:

1. Clean the brush, and begin painting with just water on the brush
2. Dip the brush into a new color of paint without a full wash cycle first
3. Dip the brush into water (without a full wash cycle), after inking the brush

(And, if these are not possible yet, let's discuss how to make them possible.)

[techninja]

Yep, all of those are totally possible, of course the given examples are restricted by the current execution logic in Robopaint. Would you like these as actual JavaScript examples? Or perhaps pseudo code?

Also, as a general explanation:
"Re-inking" is entirely controlled by the client paying attention to the pen-down distanceCounter returned for every pen request. Also there is no "full clean", this is simply a construct created by the RoboPaint client stringing together 3 water tool changes, each one waiting for the other to complete before initiating.

[oskay]

That is not what I would have understood from the existing documentation-- so there are definitely changes that need to be made.

Sets the tool for the pen. Will make all movements required to do so for the given device,
request finishes when toolchange is complete.

As "all movements required" is not defined there, I would have assumed that this meant to clean the brush first, and then move to get the new paint color. Please expand the documentation to say what this command actually does.

[techninja]

Ah, no. All API requests are meant to be as atomic as possible, and "movements required" is simple moving to that tool position, and doing the wiggle.

Honestly, even the wiggle and any brush up/down shouldn't really be part of a pure request, unless it was specified in the tool change options, or given as a default (This is probably where the dip/wiggle differentiation stuff will live in the future).

And again, the server is meant to be client agnostic, and simply listen to what you want to do, with as few assumptions as possible. The assumptions of needing a wiggle for tool changes here are grounded in the physical nature of the medium, and I agree it should be clarified in the API the full extent of the physical output of a command. Will add that to the API docs.

[oskay]

Ah, so it means "two of the movements required plus one that is not required"-- ha!

Perhaps this could be clarified to say something like "raises the brush, moves to the coordinates defined in the tool definition, lowers the brush, and (optionally) wiggles about in that location, for example to rinse the brush (if in water) or ink the brush (if in paint)" -- or otherwise accurately describe what it will do.

[techninja]

Yep. Totally agree. Though I'll leave out the "optionally" part till I've actually implemented that. As for now it'll reside with the tool definitions (unless you want me to go ahead and revert that now and work towards modifying the tool change request to include all movement options).

An important step when thinking about this is to ensure backward compatibility with older clients that may not know to pass certain options, so to ensure sane defaults.

It's that or you properly version the API ;)

[oskay]

Sorry; by "optionally," I meant depending on how it was defined in the tool definition.

[techninja]

I have yet failed to get an answer on further examples, so I'm going to assume that simply clarifying the required movements text will suffice. If not reopen this and I'll add some.