changeset 15526:15628a84a4fa stable

Document form of warning IDs is NAMESPACE:WARNING-NAME (bug #37559) * errors.txi: Add explanation of warning ID form to documentation. Correct example code to properly use warning IDs. * error.cc (Fwarning): Document form of warning ID in warning() docstring.
author Rik <rik@octave.org>
date Mon, 15 Oct 2012 07:18:31 -0700
parents 7f7a07657be4
children ae43fc2ddcac fe159d11b864
files doc/interpreter/errors.txi src/error.cc
diffstat 2 files changed, 11 insertions(+), 6 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/errors.txi
+++ b/doc/interpreter/errors.txi
@@ -296,7 +296,10 @@
 If a warning has such an ID the user can enable and disable this warning
 as will be described in the next section.  To assign an ID to a warning,
 simply call @code{warning} with two string arguments, where the first
-is the identification string, and the second is the actual warning.
+is the identification string, and the second is the actual warning.  Note
+that warning IDs are in the format "NAMESPACE:WARNING-NAME".  The namespace
+"Octave" is used for Octave's own warnings.  Any other string is available
+as a namespace for user's own warnings.
 
 @DOCSTRING(warning)
 
@@ -315,7 +318,7 @@
 
 @example
 @group
-warning ("non-negative-variable", 
+warning ("example:non-negative-variable", 
          "'a' must be non-negative.  Setting 'a' to zero.");
 @end group
 @end example
@@ -325,8 +328,8 @@
 
 @example
 @group
-warning ("off", "non-negative-variable");
-warning ("non-negative-variable", 
+warning ("off", "example:non-negative-variable");
+warning ("example:non-negative-variable", 
          "'a' must be non-negative.  Setting 'a' to zero.");
 @end group
 @end example
--- a/src/error.cc
+++ b/src/error.cc
@@ -1109,8 +1109,10 @@
 to go on.\n\
 \n\
 The optional message identifier allows users to enable or disable\n\
-warnings tagged by @var{id}.  The special identifier @samp{\"all\"} may\n\
-be used to set the state of all warnings.\n\
+warnings tagged by @var{id}.  A message identifier is of the form\n\
+\"NAMESPACE:WARNING-NAME\".  Octave's own warnings use the \"Octave\"\n\
+namespace (@pxref{doc-warning_ids}).  The special identifier @samp{\"all\"}\n\
+may be used to set the state of all warnings.\n\
 \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\