# HG changeset patch
# User Rik <rik@octave.org>
# Date 1350310711 25200
# Node ID 15628a84a4faeeb676d80a4ca1a60868073de0b0
# Parent  7f7a07657be4fb3f2f986630e4fb7cf82b6078a3
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.

diff --git a/doc/interpreter/errors.txi b/doc/interpreter/errors.txi
--- 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
diff --git a/src/error.cc b/src/error.cc
--- 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\