[MERGE] Allow self documenting hooks.

[Martin Pool]

+    * Hooks can now be self documenting. ``bzrlib.hooks.Hooks.create_hook``
+      is the entry point for this feature. (Robert Collins)

Having different classes called Foo and Foos is a bad idea because it
makes it hard to talk about the two of them precisely.  That's
probably better handled by renaming Hooks to HookSet or something.

+                strings.append("An old-style hook. For documentation
see the __init__ "
+                    "method of '%s'\n" % (self.__class__.__name__,))

Why not just insert it?

+    def hook(self, callback, callback_label):
+        """Call this hook with callback, using callback_label to describe it.
+
+        :param callback: The callable to use when this Hook fires.
+        :param callback_label: A label to show in the UI while this callback is
+            processing.
+        """
+        self._callbacks.append(callback)
+        self._callback_names[callback] = callback_label
+

I think the docstring is wrong: this doesn't actually call the hook,
it rather registers the callback to be fired.

+        strings.append("<bzrlib.hooks.Hook(")

It should be self.__class__.__name__ to allow it to be subclassed.

-- 
Martin <http://launchpad.net/~mbp/>