Merge pull request #29 from kivy/protocol_docs

Add protocol docs

docs/source/core_tutorials.rst

@@ -675,6 +675,37 @@ If you want get the SEL for ``initWithUTF8String:`` you can use::
 
 Other cases are the same for all methods.
 
+Using @protocol
+---------------
+
+Objective C protocols provide what other languages call interfaces. They specify
+a list of methods which should be implemented in order to support that protocol.
+
+Protocols define the interface which is then usually implemented by a delegate.
+Pyobjus provides us with the protocol decorator to handle this, enabling
+us to use Python objects as delegates::
+
+    @protocol('<protocol_name>')
+
+The list of protocols supported by pyobjus is contained in the
+`pyobjus/protocols.py` file in your pyobjus checkout folder. Of course, many
+libraries define their own protocols, so cannot be included by default. For
+a complete list of protocols available on you system, run the
+`tools/build_protocols.py` file and then rebuild pyobjus (as per the install).
+
+So, how do we use this decorator? We add functions with names that correspond
+to the protocol method names, then decorate these functions with the required
+protocol::
+
+    @protocol('NSURLConnectionDelegate')
+    def connection_didFailWithError_(self, connection, error):
+
+Here, we specify that our object method `connection_didFailWithError_` handles
+the `connection:didFailWithError:` delegation  of the `NSURLConnectionDelegate`
+protocol. Pyobjus then redirects this Objective-C message to our method.
+
+For a complete example, please see the `examples/delegate.py` file.
+
 Using enum types
 ----------------