Merge commit 'origin/improvements_for_mainline' into integration

* commit 'origin/improvements_for_mainline':
  Moved compatibility information of possible future release into right spot ( to the top of the release list )
  repo_tests: fixed duplicate test-method name which would redefine the previous one which never ran
  Fixed Diff class which used Commits instead of Blobs - as Blobs contain the path ( in the 'name' member variable ), the a|b_path members of Diff have been removed. Tests were adjusted and run
  git.git.Git.__init__ takes None as default argument as the execute method handles this correctly
  Fixed git.blob.Blob.blame function which would return the text-per-commit as individual characters
  improved repo documentation
  Improved head and tag object documentation slightly
  Added docs for the error module
  Added missing information to docstrings of commit and stats module
  improved git.cmd documentation
  Improved documentation on Actor and Blob

1 files changed, 32 insertions, 0 deletions

diff --git a/lib/git/stats.py b/lib/git/stats.py
index 74a23126..307e2f2f 100644
--- a/lib/git/stats.py
+++ b/lib/git/stats.py
@@ -5,6 +5,32 @@
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 
 class Stats(object):
+    """
+    Represents stat information as presented by git at the end of a merge. It is 
+    created from the output of a diff operation.
+    
+    ``Example``::
+    
+     c = Commit( sha1 )
+     s = c.stats
+     s.total         # full-stat-dict
+     s.files         # dict( filepath : stat-dict )
+     
+    ``stat-dict``
+    
+    A dictionary with the following keys and values::
+     
+      deletions = number of deleted lines as int
+      insertions = number of inserted lines as int
+      lines = total number of lines changed as int, or deletions + insertions
+      
+    ``full-stat-dict``
+    
+    In addition to the items in the stat-dict, it features additional information::
+    
+     files = number of changed files as int
+    
+    """
     def __init__(self, repo, total, files):
         self.repo = repo
         self.total = total
@@ -12,6 +38,12 @@ class Stats(object):
 
     @classmethod
     def list_from_string(cls, repo, text):
+    	"""
+    	Create a Stat object from output retrieved by git-diff.
+    	
+    	Returns
+    		git.Stat
+    	"""
         hsh = {'total': {'insertions': 0, 'deletions': 0, 'lines': 0, 'files': 0}, 'files': {}}
         for line in text.splitlines():
             (raw_insertions, raw_deletions, filename) = line.split("\t")