Improved head and tag object documentation slightly

3 files changed, 26 insertions, 24 deletions

diff --git a/lib/git/commit.py b/lib/git/commit.py
index 2d463b6e..1cb863ca 100644
--- a/lib/git/commit.py
+++ b/lib/git/commit.py
@@ -136,8 +136,8 @@ class Commit(LazyMixin):
             is an optinal path, if set only Commits that include the path 
             will be considered
 
-        ``options``
-            is a Hash of optional arguments to git where
+        ``kwargs``
+            optional keyword arguments to git where
             ``max_count`` is the maximum number of commits to fetch
             ``skip`` is the number of commits to skip
 
diff --git a/lib/git/head.py b/lib/git/head.py
index 86686f17..639cee40 100644
--- a/lib/git/head.py
+++ b/lib/git/head.py
@@ -28,16 +28,13 @@ class Head(object):
 
     def __init__(self, name, commit):
         """
-        Instantiate a new Head
+        Initialize a newly instanced Head
 
         `name`
             is the name of the head
 
         `commit`
-            is the Commit that the head points to
-
-        Returns
-            git.Head
+            is the Commit object that the head points to
         """
         self.name = name
         self.commit = commit
@@ -45,16 +42,19 @@ class Head(object):
     @classmethod
     def find_all(cls, repo, **kwargs):
         """
-        Find all Heads
+        Find all Heads in the repository
 
         `repo`
             is the Repo
 
         `kwargs`
-            is a dict of options
+            Additional options given as keyword arguments, will be passed
+            to git-for-each-ref
 
         Returns
             git.Head[]
+            
+            List is sorted by committerdate
         """
 
         options = {'sort': "committerdate",
@@ -67,12 +67,12 @@ class Head(object):
     @classmethod
     def list_from_string(cls, repo, text):
         """
-        Parse out head information into an array of baked head objects
+        Parse out head information into a list of head objects
 
         ``repo``
             is the Repo
         ``text``
-            is the text output from the git command
+            is the text output from the git-for-each-ref command
 
         Returns
             git.Head[]
@@ -95,7 +95,8 @@ class Head(object):
         ``line``
             is the formatted head information
 
-        Format
+        Format::
+        
             name: [a-zA-Z_/]+
             <null byte>
             id: [0-9A-Fa-f]{40}
diff --git a/lib/git/tag.py b/lib/git/tag.py
index f7bc140e..8413ce73 100644
--- a/lib/git/tag.py
+++ b/lib/git/tag.py
@@ -9,16 +9,13 @@ from commit import Commit
 class Tag(object):
     def __init__(self, name, commit):
         """
-        Instantiate a new Tag
+        Initialize a newly instantiated Tag
 
         ``name``
             is the name of the head
 
         ``commit``
             is the Commit that the head points to
-
-        Returns
-            ``git.Tag``
         """
         self.name = name
         self.commit = commit
@@ -26,16 +23,19 @@ class Tag(object):
     @classmethod
     def find_all(cls, repo, **kwargs):
         """
-        Find all Tags
+        Find all Tags in the repository
 
         ``repo``
             is the Repo
 
         ``kwargs``
-            is a dict of options
+            Additional options given as keyword arguments, will be passed 
+            to git-for-each-ref
 
         Returns
             ``git.Tag[]``
+            
+            List is sorted by committerdate
         """
         options = {'sort': "committerdate",
                   'format': "%(refname)%00%(objectname)"}
@@ -47,16 +47,16 @@ class Tag(object):
     @classmethod
     def list_from_string(cls, repo, text):
         """
-        Parse out tag information into an array of baked Tag objects
+        Parse out tag information into an array of Tag objects
 
         ``repo``
             is the Repo
 
         ``text``
-            is the text output from the git command
+            is the text output from the git-for-each command
 
         Returns
-            ``git.Tag[]``
+            git.Tag[]
         """
         tags = []
         for line in text.splitlines():
@@ -74,13 +74,14 @@ class Tag(object):
         ``line``
             is the formatted tag information
 
-        Format
+        Format::
+            
             name: [a-zA-Z_/]+
             <null byte>
             id: [0-9A-Fa-f]{40}
-
+        
         Returns
-            ``git.Tag``
+            git.Tag
         """
         full_name, ids = line.split("\x00")
         name = full_name.split("/")[-1]