few minor documentation cleanups

[mirror_ifupdown2.git] / ifupdown2-addons / docs / source / developmentcorner.rst

diff --git a/ifupdown2-addons/docs/source/developmentcorner.rst b/ifupdown2-addons/docs/source/developmentcorner.rst
index f70b711726beab8e7258e3944a5f5fbebedd0d3a..be5c563c576a9491fcabece82cb9f64799703448 100644 (file)
--- a/ifupdown2-addons/docs/source/developmentcorner.rst
+++ b/ifupdown2-addons/docs/source/developmentcorner.rst
@@ -3,31 +3,36 @@ Development Corner
 
 Writing a ifupdown2 addon module
 --------------------------------
-ifupdown2 addon modules are part of the python-ifupdown2 package.
-They are installed under /usr/share/ifupdownaddons directory on the target box.
+ifupdown2 addon modules are part of the python-ifupdown2-addons package.
+They are installed under /usr/share/ifupdownaddons directory on the target
+system.
 
 The center of the universe for an addon module is the 'class iface' object
 exported by the python-ifupdown2 package.
 
-The iface object contains all config the user wanted. For more details see
-the api refernce for the iface class.
-
-ifupdown2 invokes the addon module by invoking a few methods. And hence
-it expects a few interfaces from the addon modules.
-
-* all modules must inherit from moduleBase class
-* the module should implement a class by the same name
-* the interface object (class iface) and the operation to be performed is
-  passed to the modules. In cases when the operation is query-check, where
-  the module has to compare between the given and running state, the module
-  also takes an addional queryobjcur iface object
-* the python addon class should provide a few methods:
+The iface object is modeled after an iface entry in the user provided network
+configuration file (eg. /etc/network/interfaces). For more details see
+the api reference for the iface class.
+
+ifupdown2 dynamically loads a python addon module. It expects the addon module
+to implement a few methods.
+
+* all addon modules must inherit from moduleBase class
+* the module must implement a class by the same name
+* the network interface object (class iface) and the operation to be performed
+  is passed to the modules. Operation can be any of 'pre-up', 'up', 'post-up',
+  'pre-down', 'down', 'post-down', 'query-check', 'query-running'.
+  The module can choose to support a subset or all operations.
+  In cases when the operation is query-check, the module must compare between
+  the given and running state and return the checked state of the object in
+  queryobjcur passed as argument to the run menthod.
+* the python addon class must provide a few methods:
     * run() : method to configure the interface.
     * get_ops() : must return a list of operations it supports.
       eg: 'pre-up', 'post-down'
     * get_dependent_ifacenames() : must return a list of interfaces the
-      interface is dependent on. This is used to build the dependency list
-      for sorting and executing interfaces in dependency order.
+      supported interface is dependent on. This is used to build the
+      dependency list for sorting and executing interfaces in dependency order.
     * if the module supports -r option to ifquery, ie ability to construct the
       ifaceobj from running state, it can optionally implement the
       get_dependent_ifacenames_running() method, to return the list of
@@ -38,13 +43,14 @@ it expects a few interfaces from the addon modules.
     * provide a dictionary of all supported attributes in the _modinfo
       attribute. This is useful for syntax help and man page generation.
 
-python-ifupdown2 package also installs a ifupdownaddons python package that
-contains helper modules for all addon modules.
+python-ifupdown2-addons package also installs ifupdownaddons python package
+that contains helper modules for all addon modules. Its optional for the addon
+module to use this package.
 
 see example address handling module /usr/share/ifupdownaddons/address.py
 
-apiref
-------
+API reference
+-------------
 .. toctree::
    :maxdepth: 2