Add documentation for proxies (#2344)

contracts/proxy/Initializable.sol

@@ -4,16 +4,16 @@ pragma solidity >=0.4.24 <0.7.0;
 
 
 /**
- * @title Initializable
- *
- * @dev Helper contract to support initializer functions. To use it, replace
- * the constructor with a function that has the `initializer` modifier.
- * WARNING: Unlike constructors, initializer functions must be manually
- * invoked. This applies both to deploying an Initializable contract, as well
- * as extending an Initializable contract via inheritance.
- * WARNING: When used with inheritance, manual care must be taken to not invoke
- * a parent initializer twice, or ensure that all initializers are idempotent,
- * because this is not dealt with automatically as with constructors.
+ * @dev This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
+ * behind a proxy. Since a proxied contract can't have a constructor, it's common to move constructor logic to an
+ * external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer
+ * function so it can only be called once. The {initializer} modifier provided by this contract will have this effect.
+ * 
+ * TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as
+ * possible by providing the encoded function call as the `_data` argument to {UpgradeableProxy-constructor}.
+ * 
+ * CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure
+ * that all initializers are idempotent. This is not verified automatically as constructors are by Solidity.
  */
 contract Initializable {
 
@@ -28,7 +28,7 @@ contract Initializable {
     bool private _initializing;
 
     /**
-     * @dev Modifier to use in the initializer function of a contract.
+     * @dev Modifier to protect an initializer function from being invoked twice.
      */
     modifier initializer() {
         require(_initializing || _isConstructor() || !_initialized, "Initializable: contract is already initialized");