From 5a1f892361ec36fd3a7fd66b571e01af9f0e0385 Mon Sep 17 00:00:00 2001 From: ssonicblue Date: Wed, 20 Apr 2016 19:53:36 +0800 Subject: Update natspec summary in layout-of-source-files.rst Update the summary on natspec comments for clarity in what they do and how they should be used. --- docs/layout-of-source-files.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index 48ecfb09..76c13ae3 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -129,10 +129,11 @@ Single-line comments (`//`) and multi-line comments (`/*...*/`) are possible. */ -There are special types of comments called natspec comments -(documentation yet to be written). These are introduced by -triple-slash comments (`///`) or using double asterisks (`/** ... */`). -Right in front of function declarations or statements, -you can use doxygen-style tags inside them to document functions, annotate conditions for formal -verification and provide a **confirmation text** that is shown to users if they want to -invoke a function. +Additionally, there is another type of comment called a natspec comment, +for which the documentation is not yet written. They are written with a +triple slash (`///`) or a double asterisk block(`/** ... */`). +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. -- cgit v1.2.3 From 943e27a1c33ecad88aee662af6c35dcd088a22d8 Mon Sep 17 00:00:00 2001 From: ssonicblue Date: Sun, 1 May 2016 11:41:49 +0800 Subject: Minor grammatical edit --- docs/layout-of-source-files.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index 76c13ae3..7033a062 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -131,8 +131,8 @@ Single-line comments (`//`) and multi-line comments (`/*...*/`) are possible. Additionally, there is another type of comment called a natspec comment, for which the documentation is not yet written. They are written with a -triple slash (`///`) or a double asterisk block(`/** ... */`). -They should be used directly above function declarations or statements. +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 -- cgit v1.2.3