# HG changeset patch
# User Jordi Gutiérrez Hermoso <jordigh@octave.org>
# Date 1324328777 18000
# Node ID d0d9c5d2e434fc9f369126545c3c8e973bfeb442
# Parent  8aa5da1b7ce34e4b23a6aa442125c2ee9c4bfff1
doc: Reformat and clarify warning's docstring

* error.c (Vwarning): Move all calling forms to the top and provide an
  example for how to turn warnings into errors

diff -r 8aa5da1b7ce3 -r d0d9c5d2e434 src/error.cc
--- a/src/error.cc	Mon Dec 19 15:47:31 2011 -0500
+++ b/src/error.cc	Mon Dec 19 16:06:17 2011 -0500
@@ -1095,6 +1095,10 @@
   "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} warning (@var{template}, @dots{})\n\
 @deftypefnx {Built-in Function} {} warning (@var{id}, @var{template}, @dots{})\n\
+@deftypefnx {Built-in Function} {} warning (\"on\", @var{id})\n\
+@deftypefnx {Built-in Function} {} warning (\"off\", @var{id})\n\
+@deftypefnx {Built-in Function} {} warning (\"query\", @var{id})\n\
+@deftypefnx {Built-in Function} {} warning (\"error\", @var{id})\n\
 Format the optional arguments under the control of the template string\n\
 @var{template} using the same rules as the @code{printf} family of\n\
 functions (@pxref{Formatted Output}) and print the resulting message\n\
@@ -1108,14 +1112,19 @@
 warnings tagged by @var{id}.  The special identifier @samp{\"all\"} may\n\
 be used to set the state of all warnings.\n\
 \n\
-@deftypefnx {Built-in Function} {} warning (\"on\", @var{id})\n\
-@deftypefnx {Built-in Function} {} warning (\"off\", @var{id})\n\
-@deftypefnx {Built-in Function} {} warning (\"error\", @var{id})\n\
-@deftypefnx {Built-in Function} {} warning (\"query\", @var{id})\n\
-Set or query the state of a particular warning using the identifier\n\
-@var{id}.  If the identifier is omitted, a value of @samp{\"all\"} is\n\
-assumed.  If you set the state of a warning to @samp{\"error\"}, the\n\
-warning named by @var{id} is handled as if it were an error instead.\n\
+If the first argument is @samp{\"on\"} or @samp{\"off\"}, set the state\n\
+of a particular warning using the identifier @var{id}. If the first\n\
+argument is @samp{\"query\"}, query the state of this warning instead.\n\
+If the identifier is omitted, a value of @samp{\"all\"} is assumed. If\n\
+you set the state of a warning to @samp{\"error\"}, the warning named by\n\
+@var{id} is handled as if it were an error instead. So, for example, the\n\
+following handles all warnings as errors:\n\
+\n\
+@example\n\
+@group\n\
+warning (\"error\");\n\
+@end group\n\
+@end example\n\
 @seealso{warning_ids}\n\
 @end deftypefn")
 {