diff --git a/docs/natspec-format.rst b/docs/natspec-format.rst
index fa1d0c665cce..18305961e21f 100644
--- a/docs/natspec-format.rst
+++ b/docs/natspec-format.rst
@@ -28,6 +28,9 @@ Documentation Example
 Documentation is inserted above each ``class``, ``interface`` and
 ``function`` using the doxygen notation format.
 
+Note: a ``public`` state variable is equivalent to a ``function``
+for the purposes of NatSpec.
+
 -  For Solidity you may choose ``///`` for single or multi-line
    comments, or ``/**`` and ending with ``*/``.