From 3954f88b4743f7e7f96fdc0bdc6642357f63a8cc Mon Sep 17 00:00:00 2001
From: haoyang9804 <haoyanghkust@gmail.com>
Date: Fri, 18 Oct 2024 22:20:54 +0100
Subject: [PATCH] enrich document with using getter function over state struct
 instance

---
 docs/contracts/visibility-and-getters.rst | 87 ++++++++++++++++-------
 1 file changed, 61 insertions(+), 26 deletions(-)

diff --git a/docs/contracts/visibility-and-getters.rst b/docs/contracts/visibility-and-getters.rst
index 5bf46dea551b..bef5c644a5cb 100644
--- a/docs/contracts/visibility-and-getters.rst
+++ b/docs/contracts/visibility-and-getters.rst
@@ -157,19 +157,19 @@ it evaluates to a state variable.  If it is accessed externally
         }
     }
 
+When considering arrays, mapping, and structs, the getter functions do not return
+the entire state variable.
+
 If you have a ``public`` state variable of array type, then you can only retrieve
 single elements of the array via the generated getter function. This mechanism
-exists to avoid high gas costs when returning an entire array. You can use
-arguments to specify which individual element to return, for example
-``myArray(0)``. If you want to return an entire array in one call, then you need
-to write a function, for example:
+exists to avoid high gas costs when returning an entire array.
 
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.4.16 <0.9.0;
 
-    contract arrayExample {
+    contract ArrayExample {
         // public state variable
         uint[] public myArray;
 
@@ -186,18 +186,49 @@ to write a function, for example:
         }
     }
 
-Now you can use ``getArray()`` to retrieve the entire array, instead of
-``myArray(i)``, which returns a single element per call.
+If you have a ``public`` state variable of mapping type. The getter function
+returns the value associated with the key passed as an argument.
+
+.. code-block:: solidity
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity >=0.4.16 <0.9.0;
+
+    contract MappingExample {
+        // public state variable
+        mapping(uint => uint) public myMap;
+
+        // Getter function generated by the compiler
+        /*
+        function myMap(uint i) public view returns (uint) {
+            return myMap[i];
+        }
+        */
+    }
 
-The next example is more complex:
+When you declare a public state variable of a struct type, the generated getter function
+returns each member of the struct as separate elements within a tuple,
+rather than the struct as a single object in memory.
+The members returned appear in the order they are declared in the struct, provided they
+are not omitted. The mapping and arrays (with the exception of byte arrays)
+in the struct are omitted because there is no good way to
+select individual array members or provide a key for the mapping
+Additionally, if all struct members are omitted, no getter function will be generated.
 
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.4.0 <0.9.0;
+    pragma solidity >=0.4.16 <0.9.0;
 
-    contract Complex {
-        struct Data {
+    contract StructExample {
+        // Struct Definition with single member
+        struct SimpleStruct {
+            int[2] arr;
+            mapping(uint => uint) map;
+        }
+
+        // Struct Definition with multiple members
+        struct ComplexStruct {
             uint a;
             bytes3 b;
             mapping(uint => uint) map;
@@ -205,20 +236,24 @@ The next example is more complex:
             uint[] d;
             bytes e;
         }
-        mapping(uint => mapping(bool => Data[])) public data;
-    }
-
-It generates a function of the following form. The mapping and arrays (with the
-exception of byte arrays) in the struct are omitted because there is no good way
-to select individual struct members or provide a key for the mapping:
 
-.. code-block:: solidity
+        // public state variables
+        // SimpleStruct omits all its members, therefore its public instance is disallowed
+        ComplexStruct public complexStruct;
+        mapping(uint => mapping(bool => ComplexStruct[])) public map;
 
-    function data(uint arg1, bool arg2, uint arg3)
-        public
-        returns (uint a, bytes3 b, bytes memory e)
-    {
-        a = data[arg1][arg2][arg3].a;
-        b = data[arg1][arg2][arg3].b;
-        e = data[arg1][arg2][arg3].e;
-    }
+        // Getter function generated by the compiler
+        /*
+        function complexStruct() public view returns (uint, bytes3, bytes memory) {
+            return (complexStruct.a, complexStruct.b, complexStruct.e);
+        }
+        function map(uint arg1, bool arg2, uint arg3)
+            public
+            returns (uint a, bytes3 b, bytes memory e)
+        {
+            a = map[arg1][arg2][arg3].a;
+            b = map[arg1][arg2][arg3].b;
+            e = map[arg1][arg2][arg3].e;
+        }
+        */
+    }
\ No newline at end of file