[Zope3-checkins] SVN: Zope3/trunk/src/zope/ Write BBB docstrings for deprecated directives.

Florent Xicluna laxyf at yahoo.fr
Sat Aug 5 14:23:16 EDT 2006


Log message for revision 69359:
  Write BBB docstrings for deprecated directives.
  These statements should appear within ++apidoc++ for ZCML.
  
  List of deprecated directives:
  . zope
  	content
  	defaultLayer
  	defaultView
  	factory
  	localUtility *not yet deprecated*
  	modulealias
  	vocabulary
  
  . browser
  	layer
  	skin
  	tool
  
  . renderer
  	renderer
  

Changed:
  U   Zope3/trunk/src/zope/app/component/browser/metadirectives.py
  U   Zope3/trunk/src/zope/app/component/contentdirective.py
  U   Zope3/trunk/src/zope/app/component/metadirectives.py
  U   Zope3/trunk/src/zope/app/publisher/browser/metadirectives.py
  U   Zope3/trunk/src/zope/app/renderer/metaconfigure.py
  U   Zope3/trunk/src/zope/app/schema/metadirectives.py
  U   Zope3/trunk/src/zope/modulealias/metadirectives.py

-=-
Modified: Zope3/trunk/src/zope/app/component/browser/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/component/browser/metadirectives.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/app/component/browser/metadirectives.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -20,8 +20,14 @@
 
     
 class IUtilityToolDirective(Interface):
-    """Directive for creating new utility-based tools."""
+    """ *BBB: DEPRECATED*
 
+    Tools are deprecated and no-longer used.
+    The tool directive will go away in Zope 3.5.
+
+    (Directive for creating new utility-based tools.)
+    """
+
     folder = zope.configuration.fields.PythonIdentifier(
         title=u"Destination Folder",
         description=u"""Destination Folder in which the tool instances are

Modified: Zope3/trunk/src/zope/app/component/contentdirective.py
===================================================================
--- Zope3/trunk/src/zope/app/component/contentdirective.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/app/component/contentdirective.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -177,7 +177,12 @@
 
 # BBB 2006/02/24, to be removed after 12 months
 class ContentDirective(ClassDirective):
+    """ *BBB: DEPRECATED*
 
+    The ``content`` alias for the ``class`` directive has been
+    deprecated and will be removed in Zope 3.5.
+    """
+
     def __init__(self, _context, class_):
         warnings.warn_explicit(
             "The 'content' alias for the 'class' directive has been "

Modified: Zope3/trunk/src/zope/app/component/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/component/metadirectives.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/app/component/metadirectives.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -62,6 +62,8 @@
     layer = LayerField(
         title=_("The layer the view is in."),
         description=_("""
+        *BBB: DEPRECATED*
+
         A skin is composed of layers. It is common to put skin
         specific views in a layer named after the skin. If the 'layer'
         attribute is not supplied, it defaults to 'default'."""),
@@ -123,8 +125,21 @@
 
 # BBB 2006/02/24, to be removed after 12 months
 class IFactoryDirective(zope.interface.Interface):
-    """Define a factory"""
+    """
+    *BBB: DEPRECATED*
 
+    The ``factory`` directive has been deprecated and will be
+    removed in Zope 3.5.  Use the ``utility`` directive instead::
+
+      <utility
+          provides="zope.component.interfaces.IFactory"
+          component="some.factory.class"
+          name="factoryName"
+          />
+
+    (Define a factory.)
+    """
+
     component = zope.configuration.fields.GlobalObject(
         title=_("Component to be used"),
         required=True,
@@ -162,8 +177,13 @@
 ############################################################################
 # BBB: Deprecated; use browser:defaultView instead. Will go away in 3.3.
 class IDefaultViewDirective(IBasicResourceInformation):
-    """The name of the view that should be the default.
+    """
+    *BBB: DEPRECATED*
 
+    Use ``browser:defaultView`` instead.
+
+    The name of the view that should be the default.
+
     This name refers to view that should be the
     view used by default (if no view name is supplied
     explicitly).
@@ -208,8 +228,14 @@
 
 
 class IClassDirective(zope.interface.Interface):
-    """Make statements about a class"""
+    """Make statements about a class
 
+    It is discouraged to use ``content`` or ``localUtility`` directives.
+    They are no longer useful, and will be deprecated soon or later.
+
+    Only use ``class`` directive for class statements.
+    """
+
     class_ = zope.configuration.fields.GlobalObject(
         title=_("Class"),
         required=True
@@ -327,10 +353,15 @@
 
 # BBB: Deprecated. Will go away in 3.4.
 class IDefaultLayerDirective(zope.interface.Interface):
-    """Associate a default layer with a request type.
+    """
+    *BBB: DEPRECATED*
 
-    This directive has been deprecated and will go away in Zope 3.4."""
+    This directive has been deprecated and will go away in Zope 3.4.
+    It doesn't actually do anything, and never did.
 
+    (Associate a default layer with a request type.)
+    """
+
     type = zope.configuration.fields.GlobalInterface(
         title=_("Request type"),
         required=True

Modified: Zope3/trunk/src/zope/app/publisher/browser/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/publisher/browser/metadirectives.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/app/publisher/browser/metadirectives.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -568,8 +568,18 @@
 
 # BBB 2006/02/18, to be removed after 12 months
 class ILayerDirective(Interface):
-    """Defines a browser layer
+    """ *BBB: DEPRECATED*
 
+    Creating layers via ZCML has been deprecated.  The
+    'browser:layer' directive will be removed in Zope 3.5.  Layers
+    are now interfaces extending
+    'zope.publisher.interfaces.browser.IBrowserRequest'.
+    They do not need further registration.
+
+    **Previous documentation**
+
+    Defines a browser layer
+
     You must either specify a `name` or an `interface`. If you specify the
     name, then a layer interface will be created for you based on the name and
     the `base` interface.
@@ -608,8 +618,17 @@
 
 # BBB 2006/02/18, to be removed after 12 months
 class ISkinDirective(Interface):
-    """Defines a browser skin
+    """ *BBB: DEPRECATED*
 
+    Creating skins via ZCML has been deprecated.  The 'browser:skin'
+    directive will be removed in Zope 3.5.  Skins are now interfaces
+    extending 'zope.publisher.interfaces.browser.IBrowserRequest'.
+    They are registered using the 'interface' directive.
+
+    **Previous documentation**
+
+    Defines a browser skin
+
     If you do not specify an `interface`, then one will be automatically
     created for you based on the name using the layers as base interfaces.
 

Modified: Zope3/trunk/src/zope/app/renderer/metaconfigure.py
===================================================================
--- Zope3/trunk/src/zope/app/renderer/metaconfigure.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/app/renderer/metaconfigure.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -23,9 +23,25 @@
 from zope.interface import Interface
 
 class IRendererDirective(Interface):
-    """Register a renderer for a paricular output interface, such as
-    IBrowserView."""
+    """
+    *BBB: DEPRECATED*
 
+    The 'renderer' directive has been deprecated and will be
+    removed in Zope 3.5.  Use the 'view' directive instead.
+
+    Example::
+
+      <browser:view
+          name=""
+          for="some.interface"
+          class="some.class"
+          permission="zope.Public"
+          />
+
+    Register a renderer for a particular output interface, such as
+    IBrowserView.
+    """
+
     sourceType = GlobalInterface(
         title=u"Source Type Interface",
         description=u"Specifies an interface for of a particular source type.",

Modified: Zope3/trunk/src/zope/app/schema/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/schema/metadirectives.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/app/schema/metadirectives.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -21,8 +21,25 @@
 
 # BBB 2006/02/24, to be removed after 12 months
 class IVocabularyDirective(Interface):
-    '''Define a named vocabulary.
+    '''
+    *BBB: DEPRECATED*
 
+    The 'vocabulary' directive has been deprecated and will be
+    removed in Zope 3.5.  Use the 'utility' directive instead to
+    register the class as a named utility:
+
+    Example::
+
+      <utility
+          provides="zope.schema.interfaces.IVocabularyFactory"
+          component="zope.app.gary.paths.Favorites"
+          name="garys-favorite-path-references"
+          />
+
+    **Previous documentation**
+
+    Define a named vocabulary.
+
     This associates a vocabulary name in the global vocabulary registry with a
     factory.  Each name may only be defined once.
 

Modified: Zope3/trunk/src/zope/modulealias/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/modulealias/metadirectives.py	2006-08-05 17:54:32 UTC (rev 69358)
+++ Zope3/trunk/src/zope/modulealias/metadirectives.py	2006-08-05 18:23:15 UTC (rev 69359)
@@ -19,6 +19,12 @@
 from zope.interface import Interface
 
 class IModuleAliasDirective(Interface):
-    """ Define a new module alias """
+    """ *BBB: DEPRECATED*
+
+    The 'modulealias' directive has been deprecated and will be
+    removed in Zope 3.5. Manipulate 'sys.modules' manually instead.
+
+    Define a new module alias
+    """
     module = PythonIdentifier()
     alias = PythonIdentifier()



More information about the Zope3-Checkins mailing list