Update description of transformCursor

[gkubisa]

Fixes https://github.com/ottypes/docs/issues/25.

The description is a bit verbose now but hopefully makes it easier to understand what the function actually does.

[josephg]

Thanks for the edit!

Thats correct and better documentation for text types, but for something like JSON it doesn't really make sense to think about cursors as moving forwards and backwards. The whole API here is a bit weird, and I'm not sure what the best answer is. I'm going to merge this PR, but I'm not super happy about this design as it stands. I'm not sure what to do with it.

[gkubisa]

Yes, I'm also not particularly happy about that API because it seems to specific to text types.

I'm currently working on adding a generic "presence" support to ShareDB, which forced me to think about this API too. Here's what I came up with:

• createPresence(initialData: *): Presence - Creates a valid Presence from some initialData. Presence represents a user and may contain details like user ID, cursor position in a text OT type, etc. The main purpose of this function is to prevent invalid data from getting further into the system.
• transformPresence(presence: Presence, operation: Operation, isOwnOperation: boolean): Presence - Transforms the presence by the operation to create a new Presence which is adjusted in some way for the effects of the operation. For example, a cursor position may be pushed forward, if operation inserts some text at the beginning of a text document. isOwnOperation determines if the operation comes from the owner of the presence, or from another user.

The Presence for my custom text OT type is { userId: string, selectionStart: number, selectionEnd: numer } but the API above can work with any arbitrary Presence type. For example, if Presence is a number, then transformPresence === transformCursor.

Other optional functions could be added as for operations, eg normalizePresence, denormalizePresence, etc but I'd hold on with that until it's clear that they are needed.