Merge pull request #6954 from ethereum/docs-public-clar

[DOCS] Clarify that public applies to state variables

docs/miscellaneous.rst

@@ -269,7 +269,7 @@ Tips and Tricks
 
 * Use ``delete`` on arrays to delete all its elements.
 * Use shorter types for struct elements and sort them such that short types are grouped together. This can lower the gas costs as multiple ``SSTORE`` operations might be combined into a single (``SSTORE`` costs 5000 or 20000 gas, so this is what you want to optimise). Use the gas price estimator (with optimiser enabled) to check!
-* Make your state variables public - the compiler will create :ref:`getters <visibility-and-getters>` for you automatically.
+* Make your state variables public - the compiler creates :ref:`getters <visibility-and-getters>` for you automatically.
 * If you end up checking conditions on input or state a lot at the beginning of your functions, try using :ref:`modifiers`.
 * Initialize storage structs with a single assignment: ``x = MyStruct({a: 1, b: 2});``
 

docs/natspec-format.rst

@@ -36,12 +36,16 @@ Documentation is inserted above each ``class``, ``interface`` and
    documentation <https://vyper.readthedocs.io/en/latest/structure-of-a-contract.html#natspec-metadata>`__.
 
 The following example shows a contract and a function using all available tags.
-Note: NatSpec currently does NOT apply to public state variables (see
-`solidity#3418 <https://github.com/ethereum/solidity/issues/3418>`__),
-even if they are declared public and therefore do affect the ABI. Note:
-The Solidity compiler only interprets tags if they are external or
-public. You are welcome to use similar comments for your internal and
-private functions, but those will not be parsed.
+
+.. note::
+
+  NatSpec currently does NOT apply to public state variables (see
+  `solidity#3418 <https://github.com/ethereum/solidity/issues/3418>`__),
+  even if they are declared public and therefore do affect the ABI.
+
+  The Solidity compiler only interprets tags if they are external or
+  public. You are welcome to use similar comments for your internal and
+  private functions, but those will not be parsed.
 
 .. code:: solidity
 
@@ -196,4 +200,3 @@ file should also be produced and should look like this:
       },
       "title" : "A simulator for trees"
     }
-

docs/types/mapping-types.rst

@@ -25,7 +25,7 @@ in functions, or as parameters for library functions.
 They cannot be used as parameters or return parameters
 of contract functions that are publicly visible.
 
-You can mark variables of mapping type as ``public`` and Solidity creates a
+You can mark state variables of mapping type as ``public`` and Solidity creates a
 :ref:`getter <visibility-and-getters>` for you. The ``_KeyType`` becomes a
 parameter for the getter. If ``_ValueType`` is a value type or a struct,
 the getter returns ``_ValueType``.

docs/types/value-types.rst

@@ -333,7 +333,7 @@ type and this type is also used in the :ref:`ABI<ABI>`.
 Contracts do not support any operators.
 
 The members of contract types are the external functions of the contract
-including public state variables.
+including any state variables marked as ``public``.
 
 For a contract ``C`` you can use ``type(C)`` to access
 :ref:`type information<meta-type>` about the contract.