Rev 2404: Clean up add.py documentation. in http://bzr.arbash-meinel.com/branches/bzr/0.16-dev/doc-cleanup

[John Arbash Meinel]

At http://bzr.arbash-meinel.com/branches/bzr/0.16-dev/doc-cleanup

------------------------------------------------------------
revno: 2404
revision-id: john at arbash-meinel.com-20070409210631-llhncalt7gct9wms
parent: john at arbash-meinel.com-20070409210437-qdyadcg1orpe5kkh
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: doc-cleanup
timestamp: Mon 2007-04-09 16:06:31 -0500
message:
  Clean up add.py documentation.
  Add doc strings for undocumented functions.
  Move documentation to the right location for 'smart_add_tree'
  Fix rst documentation (the lines need to be indented for each parameter)
modified:
  bzrlib/add.py                  add.py-20050323030017-3a77d63feda58e33
-------------- next part --------------
=== modified file 'bzrlib/add.py'
--- a/bzrlib/add.py	2007-03-07 03:09:14 +0000
+++ b/bzrlib/add.py	2007-04-09 21:06:31 +0000
@@ -14,6 +14,8 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
+"""Helper functions for adding files to working trees."""
+
 import errno
 import os
 from os.path import dirname
@@ -29,13 +31,21 @@
 
 
 def glob_expand_for_win32(file_list):
+    """Replacement for glob expansion by the shell.
+
+    Win32's cmd.exe does not do glob expansion (eg ``*.py``), so we do our own
+    here.
+
+    :param file_list: A list of filenames which may include shell globs.
+    :return: An expanded list of filenames.
+    """
     if not file_list:
         return
     import glob
     expanded_file_list = []
     for possible_glob in file_list:
         glob_files = glob.glob(possible_glob)
-       
+
         if glob_files == []:
             # special case to let the normal code path handle
             # files that do not exists
@@ -59,6 +69,12 @@
     """A class which defines what action to take when adding a file."""
 
     def __init__(self, to_file=None, should_print=None):
+        """Initialize an action which prints added files to an output stream.
+
+        :param to_file: The stream to write into. This is expected to take
+            Unicode paths. If not supplied, it will default to ``sys.stdout``.
+        :param should_print: If False, printing will be supressed.
+        """
         self._to_file = to_file
         if to_file is None:
             self._to_file = sys.stdout
@@ -169,6 +185,21 @@
 
 
 def smart_add_tree(tree, file_list, recurse=True, action=None, save=True):
+    """Add files to version, optionally recursing into directories.
+
+    This is designed more towards DWIM for humans than API simplicity.
+    For the specific behaviour see the help for cmd_add().
+
+    This calls reporter with each (path, kind, file_id) of added files.
+
+    Returns the number of files added.
+
+    :param save: Save the inventory after completing the adds. If False this
+        provides dry-run functionality by doing the add and not saving the
+        inventory.  Note that the modified inventory is left in place, allowing
+        further dry-run tasks to take place. To restore the original inventory
+        call tree.read_working_inventory().
+    """
     tree.lock_tree_write()
     try:
         return _smart_add_tree(tree=tree, file_list=file_list, recurse=recurse,
@@ -176,21 +207,12 @@
     finally:
         tree.unlock()
 
+
 def _smart_add_tree(tree, file_list, recurse=True, action=None, save=True):
-    """Add files to version, optionally recursing into directories.
-
-    This is designed more towards DWIM for humans than API simplicity.
-    For the specific behaviour see the help for cmd_add().
-
-    This calls reporter with each (path, kind, file_id) of added files.
-
-    Returns the number of files added.
-    
-    :param save: Save the inventory after completing the adds. If False this
-    provides dry-run functionality by doing the add and not saving the
-    inventory.  Note that the modified inventory is left in place, allowing 
-    further dry-run tasks to take place. To restore the original inventory
-    call tree.read_working_inventory().
+    """Helper for smart_add_tree.
+
+    The tree should be locked before entering this function. See smart_add_tree
+    for parameter definitions.
     """
     assert isinstance(recurse, bool)
     if action is None:
@@ -347,11 +369,11 @@
 
     :param inv: Inventory which will receive the new entry.
     :param parent_ie: Parent inventory entry if known, or None.  If
-    None, the parent is looked up by name and used if present, otherwise
-    it is recursively added.
+        None, the parent is looked up by name and used if present, otherwise it
+        is recursively added.
     :param kind: Kind of new entry (file, directory, etc)
     :param action: callback(inv, parent_ie, path, kind); return ignored.
-    :returns: A list of paths which have been added.
+    :return: A list of paths which have been added.
     """
     # Nothing to do if path is already versioned.
     # This is safe from infinite recursion because the tree root is