Move the @provider example into the right section

Explain that implements()/implementsOnly()/classProvides() not only
should not be "preferred", but are entirely not functional on Python 3.

(These notes should probably use some Sphinx directive to stand out
better, but I'm not well versed in Sphinx and I don't know which one I
should use.)

1 files changed, 8 insertions, 9 deletions

diff --git a/docs/api/declarations.rst b/docs/api/declarations.rst
index dede2b3..0b978f7 100644
--- a/docs/api/declarations.rst
+++ b/docs/api/declarations.rst
@@ -37,7 +37,7 @@ implementer_only
 implements
 ----------
 
-(The `implementer` decorator is preferred to this.)
+(Does not work on Python 3.  Use the `implementer` decorator instead.)
 
 .. autofunction:: implements
 
@@ -45,7 +45,7 @@ implements
 implementsOnly
 --------------
 
-(The `implementer_only` decorator is preferred to this.)
+(Does not work on Python 3.  Use the `implementer_only` decorator instead.)
 
 .. autofunction:: implementsOnly
 
@@ -335,11 +335,16 @@ Removing an interface that is provided through the class is not possible:
 classProvides
 -------------
 
-(The `provider` decorator is preferred to this.)
+(Does not work on Python 3.  Use the `provider` decorator instead.)
 
 .. autofunction:: classProvides
 
 
+provider
+--------
+
+.. autoclass:: provider
+
 For example:
 
 .. doctest::
@@ -379,12 +384,6 @@ Which is equivalent to:
    ['IFoo']
 
 
-provider
---------
-
-.. autoclass:: provider
-
-
 moduleProvides
 --------------