Stop recommending .transfer

[fulldecent]

Page

The Address.transfer function may not be compatible with smart contract recipients due to gas limits.

Since smart contract recipients are first-class citizens on Ethereum we should either:

1. Stop recommend .transfer everywhere (in documentation) and deprecate the function, or
2. Clearly explain the limitations of .transfer everywhere it is mentioned (in documentation) and explain the difference of .call("") inline.

Discussion

I wanted to discuss this to get approval before offering any specific changes.