From 7ac891600da1dd7a992465610b24540b611e78ad Mon Sep 17 00:00:00 2001 From: Alex Beregszaszi Date: Wed, 24 Mar 2021 16:09:00 +0000 Subject: [PATCH 1/2] Properly capitalise UTF-8/ASCII in the documentation --- docs/abi-spec.rst | 4 ++-- docs/layout-of-source-files.rst | 4 ++-- docs/yul.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst index 6e897db50..63a203592 100644 --- a/docs/abi-spec.rst +++ b/docs/abi-spec.rst @@ -199,9 +199,9 @@ on the type of ``X`` being - ``string``: - ``enc(X) = enc(enc_utf8(X))``, i.e. ``X`` is utf-8 encoded and this value is interpreted + ``enc(X) = enc(enc_utf8(X))``, i.e. ``X`` is UTF-8 encoded and this value is interpreted as of ``bytes`` type and encoded further. Note that the length used in this subsequent - encoding is the number of bytes of the utf-8 encoded string, not its number of characters. + encoding is the number of bytes of the UTF-8 encoded string, not its number of characters. - ``uint``: ``enc(X)`` is the big-endian encoding of ``X``, padded on the higher-order (left) side with zero-bytes such that the length is 32 bytes. diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index 29d40619c..a0235cfa9 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -330,8 +330,8 @@ Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible .. note:: A single-line comment is terminated by any unicode line terminator - (LF, VF, FF, CR, NEL, LS or PS) in utf8 encoding. The terminator is still part of - the source code after the comment, so if it is not an ascii symbol + (LF, VF, FF, CR, NEL, LS or PS) in UTF-8 encoding. The terminator is still part of + the source code after the comment, so if it is not an ASCII symbol (these are NEL, LS and PS), it will lead to a parser error. Additionally, there is another type of comment called a natspec comment, diff --git a/docs/yul.rst b/docs/yul.rst index aff5455e7..27e35cfa0 100644 --- a/docs/yul.rst +++ b/docs/yul.rst @@ -688,7 +688,7 @@ We will use a destructuring notation for the AST nodes. Let G'', L'', mode = E(Gn, L', block) G'', Ln, L''[$ret1], ..., L''[$retm] E(G, L, l: StringLiteral) = G, L, utf8EncodeLeftAligned(l), - where utf8EncodeLeftAligned performs a utf8 encoding of l + where utf8EncodeLeftAligned performs a UTF-8 encoding of l and aligns it left into 32 bytes E(G, L, n: HexNumber) = G, L, hex(n) where hex is the hexadecimal decoding function From 78a66787d40b43f30045318a1ff008b35a26a32b Mon Sep 17 00:00:00 2001 From: Alex Beregszaszi Date: Wed, 24 Mar 2021 16:14:47 +0000 Subject: [PATCH 2/2] Improve documentation about NatSpec Clarify the connection to Doxygen. --- docs/layout-of-source-files.rst | 8 ++------ docs/natspec-format.rst | 15 +++++++++++++-- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index a0235cfa9..202ba1d9b 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -334,14 +334,10 @@ Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible the source code after the comment, so if it is not an ASCII symbol (these are NEL, LS and PS), it will lead to a parser error. -Additionally, there is another type of comment called a natspec comment, -which is detailed in the :ref:`style guide`. They are written with a +Additionally, there is another type of comment called a NatSpec comment, +which is detailed in the :ref:`style guide` section. They are written with a triple slash (``///``) or a double asterisk block(``/** ... */``) and they should be used directly above function declarations or statements. -You can use `Doxygen `_-style tags inside these comments to document -functions, annotate conditions for formal verification, and provide a -**confirmation text** which is shown to users when they attempt to invoke a -function. In the following example we document the title of the contract, the explanation for the two function parameters and two return variables. diff --git a/docs/natspec-format.rst b/docs/natspec-format.rst index 449d4d712..0c08fe010 100644 --- a/docs/natspec-format.rst +++ b/docs/natspec-format.rst @@ -8,6 +8,13 @@ Solidity contracts can use a special form of comments to provide rich documentation for functions, return variables and more. This special form is named the Ethereum Natural Language Specification Format (NatSpec). +.. note: + + NatSpec was inspired by `Doxygen `_. + While it uses Doxygen-style comments and tags, there is no intention to keep + strict compatibility with Doxygen. Please carefully examine the supported tags + listed below. + This documentation is segmented into developer-focused messages and end-user-facing messages. These messages may be shown to the end user (the human) at the time that they will interact with the contract (i.e. sign a transaction). @@ -20,13 +27,17 @@ use, and which are understood by the Solidity compiler. Also detailed below is output of the Solidity compiler, which extracts these comments into a machine-readable format. +NatSpec may also include annotations used by third-party tools. These are most likely +accomplished via the ``@custom:`` tag, and a good use case is analysis and verification +tools. + .. _header-doc-example: Documentation Example ===================== Documentation is inserted above each ``class``, ``interface`` and -``function`` using the doxygen notation format. +``function`` using the Doxygen notation format. Note: a ``public`` state variable is equivalent to a ``function`` for the purposes of NatSpec. @@ -106,7 +117,7 @@ Tag ``@author`` The name of the author contract, interface ``@notice`` Explain to an end user what this does contract, interface, function, public state variable, event ``@dev`` Explain to a developer any extra details contract, interface, function, state variable, event -``@param`` Documents a parameter just like in doxygen (must be followed by parameter name) function, event +``@param`` Documents a parameter just like in Doxygen (must be followed by parameter name) function, event ``@return`` Documents the return variables of a contract's function function, public state variable ``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable ``@custom:...`` Custom tag, semantics is application-defined everywhere