Rev 3248: Review feedback. in http://people.ubuntu.com/~robertc/baz2.0/plugin_api

[Robert Collins]

At http://people.ubuntu.com/~robertc/baz2.0/plugin_api

------------------------------------------------------------
revno: 3248
revision-id: robertc at robertcollins.net-20080404043834-wc6bp7fdls2w3rf5
parent: robertc at robertcollins.net-20080229110908-uiik8oo46rho0tn2
committer: Robert Collins <robertc at robertcollins.net>
branch nick: plugin_api
timestamp: Fri 2008-04-04 15:38:34 +1100
message:
  Review feedback.
modified:
  doc/developers/plugin-api.txt  pluginapi.txt-20080229110225-q2j5y4agqhlkjn0s-1
=== modified file 'doc/developers/plugin-api.txt'
--- a/doc/developers/plugin-api.txt	2008-02-29 11:09:08 +0000
+++ b/doc/developers/plugin-api.txt	2008-04-04 04:38:34 +0000
@@ -9,16 +9,22 @@
 
 bzrlib has a very flexible internal structure allowing plugins for many
 operations. Plugins can add commands, new storage formats, diff and merge
-features and more.
-
+features and more. This document provides an overview of the API and
+conventions for plugin authors.
 
 .. contents::
 
 
-Motivation
-==========
-
-To provide a pithy central document for plugin authors to refer to.
+Structure of a plugin
+=====================
+
+Plugins are Python modules under ``bzrlib.plugins``. They can be installed
+either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.
+
+Plugins should have a setup.py.
+
+As for other Python modules, the name of the directory must match the
+expected name of the plugin.
 
 
 Plugin metadata before installation
@@ -29,14 +35,11 @@
 such as to generate a directory of plugins, or install them via a
 symlink/checkout to ~/.bazaar/plugins.
 
-Design
-------
+This interface allows bzr to interrogate a plugin without actually loading
+it. This is useful because loading a plugin may have side effects such
+as registering or overriding commands, or the plugin may raise an error,
+if for example a prerequisite is not present.
 
-Because loading a plugin is all that is required to activate it, and
-because plugins may require external dependencies to load properly (such
-as being specific to the Windows platform), we use a separate interface to
-obtain plugin metadata from the setup.py script which plugins will
-typically have.
 
 Metadata protocol
 -----------------
@@ -97,7 +100,7 @@
 ---------------
 
 Because disk format detection for formats that bzr does not understand at
-all can be useful, we allow a declaritive description of the shape of a
+all can be useful, we allow a declarative description of the shape of a
 control directory. Each description has a name for showing to users, and a
 dictonary of relative paths, and the content needed at each path. Paths
 that end in '/' are required to be directories and the value for that key