Add a WARNING pragma

3 files changed, 38 insertions, 30 deletions

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 8da67f887c..f13d34ca20 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1005,10 +1005,10 @@
 	  </row>
 
 	  <row>
-	    <entry><option>-fwarn-deprecations</option></entry>
-	    <entry>warn about uses of functions &amp; types that are deprecated</entry>
+	    <entry><option>-fwarn-warnings-deprecations</option></entry>
+	    <entry>warn about uses of functions &amp; types that have warnings or deprecated pragmas</entry>
 	    <entry>dynamic</entry>
-	    <entry><option>-fno-warn-deprecations</option></entry>
+	    <entry><option>-fno-warn-warnings-deprecations</option></entry>
 	  </row>
 
 	  <row>
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index a100e43e77..0f55b9b4e1 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -6162,56 +6162,63 @@ Assertion failures can be caught, see the documentation for the
 	don't recommend using this approach with GHC.</para>
     </sect2>
 
-    <sect2 id="deprecated-pragma">
-      <title>DEPRECATED pragma</title>
-      <indexterm><primary>DEPRECATED</primary>
-      </indexterm>
+    <sect2 id="warning-deprecated-pragma">
+      <title>WARNING and DEPRECATED pragmas</title>
+      <indexterm><primary>WARNING</primary></indexterm>
+      <indexterm><primary>DEPRECATED</primary></indexterm>
 
-      <para>The DEPRECATED pragma lets you specify that a particular
-      function, class, or type, is deprecated.  There are two
-      forms.
+      <para>The WARNING pragma allows you to attach an arbitrary warning
+      to a particular function, class, or type.
+      A DEPRECATED pragma lets you specify that
+      a particular function, class, or type is deprecated.
+      There are two ways of using these pragmas.
 
       <itemizedlist>
 	<listitem>
-	  <para>You can deprecate an entire module thus:</para>
+	  <para>You can work on an entire module thus:</para>
 <programlisting>
    module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
      ...
 </programlisting>
+      <para>Or:</para>
+<programlisting>
+   module Wibble {-# WARNING "This is an unstable interface." #-} where
+     ...
+</programlisting>
 	  <para>When you compile any module that import
           <literal>Wibble</literal>, GHC will print the specified
           message.</para>
 	</listitem>
 
 	<listitem>
-	  <para>You can deprecate a function, class, type, or data constructor, with the
-	  following top-level declaration:</para>
+	  <para>You can attach a warning to a function, class, type, or data constructor, with the
+	  following top-level declarations:</para>
 <programlisting>
    {-# DEPRECATED f, C, T "Don't use these" #-}
+   {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-}
 </programlisting>
 	  <para>When you compile any module that imports and uses any
           of the specified entities, GHC will print the specified
           message.</para>
-	  <para> You can only deprecate entities declared at top level in the module
+	  <para> You can only attach to entities declared at top level in the module
 	  being compiled, and you can only use unqualified names in the list of
-	  entities being deprecated.  A capitalised name, such as <literal>T</literal>
+	  entities. A capitalised name, such as <literal>T</literal>
 	  refers to <emphasis>either</emphasis> the type constructor <literal>T</literal>
 	  <emphasis>or</emphasis> the data constructor <literal>T</literal>, or both if
-	  both are in scope.  If both are in scope, there is currently no way to deprecate 
-	  one without the other (c.f. fixities <xref linkend="infix-tycons"/>).</para>
+	  both are in scope.  If both are in scope, there is currently no way to
+      specify one without the other (c.f. fixities
+      <xref linkend="infix-tycons"/>).</para>
 	</listitem>
       </itemizedlist>
-      Any use of the deprecated item, or of anything from a deprecated
-      module, will be flagged with an appropriate message.  However,
-      deprecations are not reported for
-      (a) uses of a deprecated function within its defining module, and
-      (b) uses of a deprecated function in an export list.
+      Warnings and deprecations are not reported for
+      (a) uses within the defining module, and
+      (b) uses in an export list.
       The latter reduces spurious complaints within a library
       in which one module gathers together and re-exports 
       the exports of several others.
       </para>
       <para>You can suppress the warnings with the flag
-      <option>-fno-warn-deprecations</option>.</para>
+      <option>-fno-warn-warnings-deprecations</option>.</para>
     </sect2>
 
     <sect2 id="inline-noinline-pragma">
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 3c19be5de2..4b3024ae9b 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -841,7 +841,7 @@ ghc -c Foo.hs</screen>
     of warnings which are generally likely to indicate bugs in your
     program.  These are:
     <option>-fwarn-overlapping-patterns</option>,
-    <option>-fwarn-deprecations</option>,
+    <option>-fwarn-warnings-deprecations</option>,
     <option>-fwarn-deprecated-flags</option>,
     <option>-fwarn-duplicate-exports</option>,
     <option>-fwarn-missing-fields</option>,
@@ -919,15 +919,16 @@ ghc -c Foo.hs</screen>
     <variablelist>
 
       <varlistentry>
-	<term><option>-fwarn-deprecations</option>:</term>
+	<term><option>-fwarn-warnings-deprecations</option>:</term>
 	<listitem>
-	  <indexterm><primary><option>-fwarn-deprecations</option></primary>
+	  <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
 	  </indexterm>
+	  <indexterm><primary>warnings</primary></indexterm>
 	  <indexterm><primary>deprecations</primary></indexterm>
-	  <para>Causes a warning to be emitted when a deprecated
-	  function or type is used.  Entities can be marked as
-	  deprecated using a pragma, see <xref
-	  linkend="deprecated-pragma"/>.</para>
+	  <para>Causes a warning to be emitted when a
+	  module, function or type with a WARNING or DEPRECATED pragma
+      is used. See <xref linkend="warning-deprecated-pragma"/> for more
+      details on the pragmas.</para>
 
 	  <para>This option is on by default.</para>
 	</listitem>