Fix order of subtraction

[Aerilius]

It was not clear to me what is subtracted from what, and which method (subtract/trim) is non-desctructive.

• Fix order of subtraction: When I subtract this from arg, it should equal arg - this
• documentation of side-effects which groups/instances are deleted (#<Deleted Entity>)

[DanRathbun]

I wish Ruby docs would not use "this" as it is a JavaScript identifier. Ruby docs should always use "self" or "itself" (which has been recently added to the language.)

[DanRathbun]

@Aerilius, This snippet suggestion would need to be opened as a documentation Issue in the API tracker.

(The stubs are generated from the C code comments and Thomas' script that used to accept PRs to change the core code has been broken for quite some time.)

[DanRathbun]

If this is opened as a API documentation issue, then this can be rejected and closed.

I agree with most of the descriptive changes proposed except that ...
"replaced by the result of subtracting the first from the second instance."
would be better as:
"replaced by the result of subtracting the receiver instance from the argument instance."