Merge pull request #5977 from ethereum/enhance_docs

Enhance documentation about usage of `value` and `gas`

docs/control-structures.rst

@@ -91,7 +91,7 @@ You need to use the modifier ``payable`` with the ``info`` function because
 otherwise, the ``.value()`` option would not be available.
 
 .. warning::
-  Be careful that ``feed.info.value(10).gas(800)`` only locally sets the ``value`` and amount of ``gas`` sent with the function call, and the parentheses at the end perform the actual call. So in this case, the function is not called.
+  Be careful that ``feed.info.value(10).gas(800)`` only locally sets the ``value`` and amount of ``gas`` sent with the function call, and the parentheses at the end perform the actual call. So in this case, the function is not called and the ``value`` and ``gas`` settings are lost.
 
 Function calls cause exceptions if the called contract does not exist (in the
 sense that the account does not contain code) or if the called contract itself

docs/types/value-types.rst

@@ -614,15 +614,23 @@ just use ``f``, if you want to use its external form, use ``this.f``.
 
 Members:
 
-Public (or external) functions also have a special member called ``selector``,
-which returns the :ref:`ABI function selector <abi_function_selector>`::
+Public (or external) functions have the following members:
+
+* ``.selector`` returns the :ref:`ABI function selector <abi_function_selector>`
+* ``.gas(uint)`` returns a callable function object which, when called, will send the specified amount of gas to the target function. See :ref:`External Function Calls <external-function-calls>` for more information.
+* ``.value(uint)`` returns a callable function object which, when called, will send the specified amount of wei to the target function. See :ref:`External Function Calls <external-function-calls>` for more information.
+
+Example that shows how to use the members::
 
     pragma solidity >=0.4.16 <0.6.0;
 
-    contract Selector {
-      function f() public pure returns (bytes4) {
+    contract Example {
+      function f() public payable returns (bytes4) {
         return this.f.selector;
       }
+      function g() public {
+        this.f.gas(10).value(800)();
+      }
     }
 
 Example that shows how to use internal function types::