Ticket #5174: ticket-5174-2-docs.patch

File ticket-5174-2-docs.patch, 5.4 KB (added by wirehead, 13 months ago)

v2 patch, fixed a few more things.

  • twisted/python/components.py

     
    190190 
    191191 
    192192class Componentized: 
    193     """I am a mixin to allow you to be adapted in various ways persistently. 
     193    """ 
     194    Componentized is a mixin to allow you to be adapted in various ways 
     195    persistently. 
    194196 
    195     I define a list of persistent adapters.  This is to allow adapter classes 
    196     to store system-specific state, and initialized on demand.  The 
    197     getComponent method implements this.  You must also register adapters for 
    198     this class for the interfaces that you wish to pass to getComponent. 
     197    Componentized define a list of persistent adapters.  This is to allow 
     198    adapter classes to store system-specific state, and initialized on demand. 
     199    The getComponent method implements this.  You must also register adapters 
     200    for this class for the interfaces that you wish to pass to getComponent. 
    199201 
    200202    Many other classes and utilities listed here are present in Zope3; this one 
    201203    is specific to Twisted. 
     
    207209        self._adapterCache = {} 
    208210 
    209211    def locateAdapterClass(self, klass, interfaceClass, default): 
     212        """ 
     213        Return registered adapter for a given class and interface. 
     214 
     215        Note that is tied to the *Twisted* global registry, and will 
     216        thus not find adapters registered elsewhere. 
     217 
     218        @param klass: The adapter class 
     219 
     220        @param interfaceClass: the interface class. 
     221 
     222        #param default: The default adapter to return. 
     223        """ 
    210224        return getAdapterFactory(klass, interfaceClass, default) 
    211225 
    212226    def setAdapter(self, interfaceClass, adapterClass): 
    213227        """ 
    214228        Cache a provider for the given interface, by adapting C{self} using 
    215229        the given adapter class. 
     230 
     231        @param interfaceClass: the interface class. 
     232 
     233        #param adapterClass: the adapter class to register 
    216234        """ 
    217235        self.setComponent(interfaceClass, adapterClass(self)) 
    218236 
    219237    def addAdapter(self, adapterClass, ignoreClass=0): 
    220         """Utility method that calls addComponent.  I take an adapter class and 
    221         instantiate it with myself as the first argument. 
     238        """Utility method that calls addComponent. 
    222239 
     240        @param adapterClass: The component to be instantiated with  
     241        the current object as the first argument.   
     242 
     243        @param ignoreClass: In order to determine which interfaces are  
     244        appropriate, the component's provided interfaces will be scanned.  
     245        If the argument 'ignoreClass' is True, then all interfaces are 
     246        considered appropriate. 
     247 
    223248        @return: The adapter instantiated. 
    224249        """ 
    225250        adapt = adapterClass(self) 
     
    229254    def setComponent(self, interfaceClass, component): 
    230255        """ 
    231256        Cache a provider of the given interface. 
     257 
     258        @param interfaceClass: The interface class the component  
     259        is an adapter for. 
     260 
     261        @param component: The component to be added. 
    232262        """ 
    233263        self._adapterCache[reflect.qual(interfaceClass)] = component 
    234264 
    235265    def addComponent(self, component, ignoreClass=0): 
    236266        """ 
    237         Add a component to me, for all appropriate interfaces. 
     267        Add a component, for all appropriate interfaces. 
    238268 
    239         In order to determine which interfaces are appropriate, the component's 
    240         provided interfaces will be scanned. 
     269        @param component: The component to be added. 
    241270 
     271        @param ignoreClass: In order to determine which interfaces are  
     272        appropriate, the component's provided interfaces will be scanned.  
    242273        If the argument 'ignoreClass' is True, then all interfaces are 
    243274        considered appropriate. 
    244275 
    245276        Otherwise, an 'appropriate' interface is one for which its class has 
    246277        been registered as an adapter for my class according to the rules of 
    247278        getComponent. 
    248  
    249         @return: the list of appropriate interfaces 
    250279        """ 
    251280        for iface in declarations.providedBy(component): 
    252281            if (ignoreClass or 
     
    255284                self._adapterCache[reflect.qual(iface)] = component 
    256285 
    257286    def unsetComponent(self, interfaceClass): 
    258         """Remove my component specified by the given interface class.""" 
     287        """ 
     288        Remove the component specified by the given interface class. 
     289 
     290        @param interfaceClass: The interface class to be removed. 
     291        """ 
    259292        del self._adapterCache[reflect.qual(interfaceClass)] 
    260293 
    261294    def removeComponent(self, component): 
    262295        """ 
    263         Remove the given component from me entirely, for all interfaces for which 
     296        Remove the given component entirely, for all interfaces for which 
    264297        it has been registered. 
    265298 
     299        @param component: The component to be removed. 
     300 
    266301        @return: a list of the interfaces that were removed. 
    267302        """ 
    268303        l = [] 
     
    287322        If you want to automatically register an adapter for all appropriate 
    288323        interfaces (with addComponent), set the attribute 'multiComponent' to 
    289324        True on your adapter class. 
     325 
     326        @param interface: The interface to be added 
     327 
     328        @param default: The default adapter to return if there isn't one  
     329        already present. 
     330 
     331        @return: default or an adapter for the interface. 
    290332        """ 
    291333        k = reflect.qual(interface) 
    292334        if k in self._adapterCache: