From cf5aa450bdbf2188a83e80221eb4a9f67b630bda Mon Sep 17 00:00:00 2001
From: chriseth <chris@ethereum.org>
Date: Tue, 16 Jun 2020 18:20:37 +0200
Subject: [PATCH] Documentation.

---
 Changelog.md                          |  1 +
 docs/Solidity.g4                      |  2 +-
 docs/contracts/function-modifiers.rst |  2 +-
 docs/contracts/functions.rst          | 28 +++++++++++++++++++++++++++
 docs/layout-of-source-files.rst       |  2 +-
 docs/structure-of-a-contract.rst      | 11 +++++++++--
 6 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/Changelog.md b/Changelog.md
index 9235faf6e..4b47af706 100644
--- a/Changelog.md
+++ b/Changelog.md
@@ -1,6 +1,7 @@
 ### 0.7.1 (unreleased)
 
 Language Features:
+ * Allow function definitions outside of contracts, behaving much like internal library functions.
 
 
 Compiler Features:
diff --git a/docs/Solidity.g4 b/docs/Solidity.g4
index 91f59d78c..dee054492 100644
--- a/docs/Solidity.g4
+++ b/docs/Solidity.g4
@@ -8,7 +8,7 @@
 grammar Solidity;
 
 sourceUnit
-  : (pragmaDirective | importDirective | structDefinition | enumDefinition | contractDefinition)* EOF ;
+  : (pragmaDirective | importDirective | structDefinition | enumDefinition | functionDefinition | contractDefinition)* EOF ;
 
 pragmaDirective
   : 'pragma' pragmaName ( ~';' )* ';' ;
diff --git a/docs/contracts/function-modifiers.rst b/docs/contracts/function-modifiers.rst
index 823e6e6ac..881b8f787 100644
--- a/docs/contracts/function-modifiers.rst
+++ b/docs/contracts/function-modifiers.rst
@@ -18,7 +18,7 @@ if they are marked ``virtual``. For details, please see
 ::
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.6.99 <0.8.0;
+    pragma solidity >0.7.0 <0.8.0;
 
     contract owned {
         constructor() { owner = msg.sender; }
diff --git a/docs/contracts/functions.rst b/docs/contracts/functions.rst
index 41174c958..e7c97c33d 100644
--- a/docs/contracts/functions.rst
+++ b/docs/contracts/functions.rst
@@ -6,6 +6,34 @@
 Functions
 *********
 
+Functions can be defined inside and outside of contracts.
+
+Functions outside of a contract, also called "free functions", always have implicit ``internal``
+:ref:`visibility<visibility-and-getters>`. Their code is included in all contracts
+that call them, similar to internal library functions.
+
+::
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity >0.7.0 <0.8.0;
+
+    function sum(uint[] memory _arr) pure returns (uint s) {
+        for (uint i = 0; i < _arr.length; i++)
+            s += _arr[i];
+    }
+
+    contract ArrayExample {
+        bool found;
+        function f(uint[] memory _arr) public {
+            // This calls the free function internally.
+            // The compiler will add its code to the contract.
+            uint s = sum(_arr);
+            require(s >= 10);
+            found = true;
+        }
+    }
+
+
 .. _function-parameters-return-variables:
 
 Function Parameters and Return Variables
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
index d50ea06a3..d80af49f7 100644
--- a/docs/layout-of-source-files.rst
+++ b/docs/layout-of-source-files.rst
@@ -5,7 +5,7 @@ Layout of a Solidity Source File
 Source files can contain an arbitrary number of
 :ref:`contract definitions<contract_structure>`, import_ directives,
 :ref:`pragma directives<pragma>` and
-:ref:`struct<structs>` and :ref:`enum<enums>` definitions.
+:ref:`struct<structs>`, :ref:`enum<enums>` and :ref:`function<functions>` definitions.
 
 .. index:: ! license, spdx
 
diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst
index 016130730..80cd5f617 100644
--- a/docs/structure-of-a-contract.rst
+++ b/docs/structure-of-a-contract.rst
@@ -43,12 +43,14 @@ visibility.
 Functions
 =========
 
-Functions are the executable units of code within a contract.
+Functions are the executable units of code. Functions are usually
+defined inside a contract, but they can also be defined outside of
+contracts.
 
 ::
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.4.0 <0.8.0;
+    pragma solidity >0.7.0 <0.8.0;
 
     contract SimpleAuction {
         function bid() public payable { // Function
@@ -56,6 +58,11 @@ Functions are the executable units of code within a contract.
         }
     }
 
+    // Helper function defined outside of a contract
+    function helper(uint x) pure returns (uint) {
+        return x * 2;
+    }
+
 :ref:`function-calls` can happen internally or externally
 and have different levels of :ref:`visibility<visibility-and-getters>`
 towards other contracts. :ref:`Functions<functions>` accept :ref:`parameters and return variables<function-parameters-return-variables>` to pass parameters