aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src
diff options
context:
space:
mode:
authorRichard Carlsson <[email protected]>2016-10-29 17:24:25 +0200
committerRichard Carlsson <[email protected]>2016-11-29 14:10:12 +0100
commitd2be06f9c113812a1ffd56e0fdc25c28cdbf0abf (patch)
tree193979cfd190f969e4b87b622f5d8febbee75a29 /lib/stdlib/doc/src
parentc49194c9239c0dcad17b902b6638edf53bb69c6c (diff)
downloadotp-d2be06f9c113812a1ffd56e0fdc25c28cdbf0abf.tar.gz
otp-d2be06f9c113812a1ffd56e0fdc25c28cdbf0abf.tar.bz2
otp-d2be06f9c113812a1ffd56e0fdc25c28cdbf0abf.zip
Add comment-versions of assert macros
For all assert macros in assert.hrl, add corresponding versions with an additional last Comment argument, assumed to be chardata. If an exception occurs, it will contain an entry {comment, Comment}, which a reporting tool may pretty-print for better readability.
Diffstat (limited to 'lib/stdlib/doc/src')
-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>