aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-11-30 09:51:59 +0100
committerBjörn Gustavsson <[email protected]>2016-11-30 09:51:59 +0100
commitc2deecfd351492ef4daeb2184d62cc2e6fb1659a (patch)
tree280299a67e48738538c56d73a4040babb95bc4f1 /lib/stdlib/doc
parent448b12eb58fd72464c70a493ca77af5c5a9a2a09 (diff)
parentd2be06f9c113812a1ffd56e0fdc25c28cdbf0abf (diff)
downloadotp-c2deecfd351492ef4daeb2184d62cc2e6fb1659a.tar.gz
otp-c2deecfd351492ef4daeb2184d62cc2e6fb1659a.tar.bz2
otp-c2deecfd351492ef4daeb2184d62cc2e6fb1659a.zip
Merge branch 'richcarl/assert-comments/PR-1224/OTP-14066'
* richcarl/assert-comments/PR-1224/OTP-14066: Add comment-versions of assert macros
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/assert_hrl.xml33
1 files changed, 26 insertions, 7 deletions
diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml
index e2dfc2ab9b..a29f6d6ad7 100644
--- a/lib/stdlib/doc/src/assert_hrl.xml
+++ b/lib/stdlib/doc/src/assert_hrl.xml
@@ -28,7 +28,7 @@
<date></date>
<rev></rev>
</header>
- <file>assert.hrl.xml</file>
+ <file>assert.hrl</file>
<filesummary>Assert macros.</filesummary>
<description>
<p>The include file <c>assert.hrl</c> provides macros for inserting
@@ -49,25 +49,33 @@
entries in the <c>Info</c> list are optional; do not rely programatically
on any of them being present.</p>
+ <p>Each assert macro has a corresponding version with an extra argument,
+ for adding comments to assertions. These can for example be printed as
+ part of error reports, to clarify the meaning of the check that
+ failed. For example, <c>?assertEqual(0, fib(0), "Fibonacci is defined
+ for zero")</c>. The comment text can be any character data (string,
+ UTF8-binary, or deep list of such data), and will be included in the
+ error term as <c>{comment, Text}</c>.</p>
+
<p>If the macro <c>NOASSERT</c> is defined when <c>assert.hrl</c> is read
by the compiler, the macros are defined as equivalent to the atom
- <c>ok</c>. The test is not performed and there is no cost at runtime.</p>
+ <c>ok</c>. The test will not be performed and there is no cost at runtime.</p>
<p>For example, using <c>erlc</c> to compile your modules, the following
- disable all assertions:</p>
+ disables all assertions:</p>
<code type="none">
erlc -DNOASSERT=true *.erl</code>
- <p>The value of <c>NOASSERT</c> does not matter, only the fact that it is
- defined.</p>
+ <p>(The value of <c>NOASSERT</c> does not matter, only the fact that it is
+ defined.)</p>
<p>A few other macros also have effect on the enabling or disabling of
assertions:</p>
<list type="bulleted">
- <item><p>If <c>NODEBUG</c> is defined, it implies <c>NOASSERT</c>, unless
- <c>DEBUG</c> is also defined, which is assumed to take precedence.</p>
+ <item><p>If <c>NODEBUG</c> is defined, it implies <c>NOASSERT</c> (unless
+ <c>DEBUG</c> is also defined, which overrides <c>NODEBUG</c>).</p>
</item>
<item><p>If <c>ASSERT</c> is defined, it overrides <c>NOASSERT</c>, that
is, the assertions remain enabled.</p></item>
@@ -84,16 +92,19 @@ erlc -DNOASSERT=true *.erl</code>
<title>Macros</title>
<taglist>
<tag><c>assert(BoolExpr)</c></tag>
+ <tag><c>assert(BoolExpr, Comment)</c></tag>
<item>
<p>Tests that <c>BoolExpr</c> completes normally returning
<c>true</c>.</p>
</item>
<tag><c>assertNot(BoolExpr)</c></tag>
+ <tag><c>assertNot(BoolExpr, Comment)</c></tag>
<item>
<p>Tests that <c>BoolExpr</c> completes normally returning
<c>false</c>.</p>
</item>
<tag><c>assertMatch(GuardedPattern, Expr)</c></tag>
+ <tag><c>assertMatch(GuardedPattern, Expr, Comment)</c></tag>
<item>
<p>Tests that <c>Expr</c> completes normally yielding a value that
matches <c>GuardedPattern</c>, for example:</p>
@@ -104,6 +115,7 @@ erlc -DNOASSERT=true *.erl</code>
?assertMatch({bork, X} when X > 0, f())</code>
</item>
<tag><c>assertNotMatch(GuardedPattern, Expr)</c></tag>
+ <tag><c>assertNotMatch(GuardedPattern, Expr, Comment)</c></tag>
<item>
<p>Tests that <c>Expr</c> completes normally yielding a value that does
not match <c>GuardedPattern</c>.</p>
@@ -111,16 +123,19 @@ erlc -DNOASSERT=true *.erl</code>
<c>when</c> part.</p>
</item>
<tag><c>assertEqual(ExpectedValue, Expr)</c></tag>
+ <tag><c>assertEqual(ExpectedValue, Expr, Comment)</c></tag>
<item>
<p>Tests that <c>Expr</c> completes normally yielding a value that is
exactly equal to <c>ExpectedValue</c>.</p>
</item>
<tag><c>assertNotEqual(ExpectedValue, Expr)</c></tag>
+ <tag><c>assertNotEqual(ExpectedValue, Expr, Comment)</c></tag>
<item>
<p>Tests that <c>Expr</c> completes normally yielding a value that is
not exactly equal to <c>ExpectedValue</c>.</p>
</item>
<tag><c>assertException(Class, Term, Expr)</c></tag>
+ <tag><c>assertException(Class, Term, Expr, Comment)</c></tag>
<item>
<p>Tests that <c>Expr</c> completes abnormally with an exception of type
<c>Class</c> and with the associated <c>Term</c>. The assertion fails
@@ -130,6 +145,7 @@ erlc -DNOASSERT=true *.erl</code>
patterns, as in <c>assertMatch</c>.</p>
</item>
<tag><c>assertNotException(Class, Term, Expr)</c></tag>
+ <tag><c>assertNotException(Class, Term, Expr, Comment)</c></tag>
<item>
<p>Tests that <c>Expr</c> does not evaluate abnormally with an
exception of type <c>Class</c> and with the associated <c>Term</c>.
@@ -139,14 +155,17 @@ erlc -DNOASSERT=true *.erl</code>
be guarded patterns.</p>
</item>
<tag><c>assertError(Term, Expr)</c></tag>
+ <tag><c>assertError(Term, Expr, Comment)</c></tag>
<item>
<p>Equivalent to <c>assertException(error, Term, Expr)</c></p>
</item>
<tag><c>assertExit(Term, Expr)</c></tag>
+ <tag><c>assertExit(Term, Expr, Comment)</c></tag>
<item>
<p>Equivalent to <c>assertException(exit, Term, Expr)</c></p>
</item>
<tag><c>assertThrow(Term, Expr)</c></tag>
+ <tag><c>assertThrow(Term, Expr, Comment)</c></tag>
<item>
<p>Equivalent to <c>assertException(throw, Term, Expr)</c></p>
</item>