Add working example, clearer description, reorder arguments as in sig…

[Aerilius]

The example of the method Sketchup::Entities#intersect_with was not helpful for understanding how this rather complex method works.

• I added a working example
• clearer description
• reordered arguments to the same order as in the method signature
• renamed arguments so that entities and corresponding transform have matching number. Previously one could think transform1 refers the transformation of entities1 although it refers to the receiver. One could also think transform2 refers to the list of entities entities2 although it refers to the target context for the intersection lines entities1.

[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]

Do we have a complimentary documentation issue open in the API tracker ?
(Does not look like it.) If this done, then this can be rejected and closed.

[DanRathbun]

@thomthom This PR Issue can be rejected and closed as it way behind and you're no longer accepting PRs for the docs.
A complementary issue has been opened in the API tracker as: Issue 741 : Add better examples for entities.intersect_with