python-fastimport: overview documentation

Add some docstrings to help new readers to get started.

Signed-off-by: Jelmer Vernooij <jelmer@samba.org>

4 files changed, 41 insertions, 7 deletions

diff --git a/fastimport/__init__.py b/fastimport/__init__.py
index 3f2ec5a..37265b8 100644
--- a/fastimport/__init__.py
+++ b/fastimport/__init__.py
@@ -13,6 +13,21 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Fastimport streams."""
+"""Fastimport file format parser and generator
+
+This is a Python parser for git's fast-import format.  It was
+originally developed for bzr-fastimport but has been extracted so
+it can be used by other projects.  Use it like so:
+
+   import fastimport.processor
+   import fastimport.parser
+
+   class ImportProcessor(fastimport.processor.ImportProcessor):
+       ...
+
+   parser = fastimport.parser.ImportParser(sys.stdin)
+   processor = ImportProcessor(...)
+   processor.process(parser.parse())
+"""
 
 __version__ = (0, 9, 4)
diff --git a/fastimport/commands.py b/fastimport/commands.py
index c1a4d05..0a0fce5 100644
--- a/fastimport/commands.py
+++ b/fastimport/commands.py
@@ -13,7 +13,11 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Import command classes."""
+"""fast-import command classes.
+
+These objects are used by the parser to represent the content of
+a fast-import stream.
+"""
 
 import stat
 
@@ -58,6 +62,8 @@ class ImportCommand(object):
     def dump_str(self, names=None, child_lists=None, verbose=False):
         """Dump fields as a string.
 
+        For debugging.
+
         :param names: the list of fields to include or
             None for all public fields
         :param child_lists: dictionary of child command names to
diff --git a/fastimport/dates.py b/fastimport/dates.py
index 65223f8..96efcf2 100644
--- a/fastimport/dates.py
+++ b/fastimport/dates.py
@@ -15,7 +15,9 @@
 
 """Date parsing routines.
 
-Each routine returns timestamp,timezone where
+Each routine represents a date format that can be specified in a
+stream using the date-format feature.  The return value is
+timestamp,timezone where
 
 * timestamp is seconds since epoch
 * timezone is the offset from UTC in seconds.
diff --git a/fastimport/processor.py b/fastimport/processor.py
index df00e2d..d71b98f 100644
--- a/fastimport/processor.py
+++ b/fastimport/processor.py
@@ -13,10 +13,21 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Processor of import commands.
+"""Processor for fast-import commands.
 
-This module provides core processing functionality including an abstract class
-for basing real processors on. See the processors package for examples.
+This module provides the skeleton of a fast-import backend.
+To import from a fast-import stream to your version-control system:
+
+ - derive a class from the abstract ImportProcessor class and
+   implement the *_helper methods.
+
+ - parse a fast-import stream into a sequence of commands, for example
+   using the helpers from the parser module.
+
+ - pass that command sequence to the process method of your processor.
+
+See git-fast-import.1 for the meaning of each command and the
+processors package for examples.
 """
 
 import sys
@@ -26,7 +37,7 @@ import errors
 
 
 class ImportProcessor(object):
-    """Base class for import processors.
+    """Base class for fast-import stream processors.
 
     Subclasses should override the pre_*, post_* and *_handler
     methods as appropriate.