Updated and fixed sphinx API docs, which included one quick skim-through

3 files changed, 25 insertions, 19 deletions

diff --git a/lib/git/index/base.py b/lib/git/index/base.py
index 03da52b7..1a8bee93 100644
--- a/lib/git/index/base.py
+++ b/lib/git/index/base.py
@@ -4,7 +4,7 @@
 # This module is part of GitPython and is released under
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 """Module containing Index implementation, allowing to perform all kinds of index
-manipulations such as querying and merging. """
+manipulations such as querying and merging."""
 import tempfile
 import os
 import sys
@@ -75,22 +75,26 @@ __all__ = ( 'IndexFile', 'CheckoutError' )
 
 
 class IndexFile(LazyMixin, diff.Diffable, Serializable):
-	"""Implements an Index that can be manipulated using a native implementation in
+	"""
+	Implements an Index that can be manipulated using a native implementation in
 	order to save git command function calls wherever possible.
-
+	
 	It provides custom merging facilities allowing to merge without actually changing
 	your index or your working tree. This way you can perform own test-merges based
 	on the index only without having to deal with the working copy. This is useful
 	in case of partial working trees.
 
 	``Entries``
+	
 	The index contains an entries dict whose keys are tuples of type IndexEntry
 	to facilitate access.
 
 	You may read the entries dict or manipulate it using IndexEntry instance, i.e.::
+	
 		index.entries[index.entry_key(index_entry_instance)] = index_entry_instance
-	Otherwise changes to it will be lost when changing the index using its methods.
-	"""
+	
+	Make sure you use index.write() once you are done manipulating the index directly
+	before operating on it using the git command"""
 	__slots__ = ("repo", "version", "entries", "_extension_data", "_file_path")
 	_VERSION = 2			# latest version we support
 	S_IFGITLINK = 0160000	# a submodule
@@ -250,7 +254,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 
 		:param repo: The repository treeish are located in.
 
-		:param *tree_sha:
+		:param tree_sha:
 			20 byte or 40 byte tree sha or tree objects 
 
 		:return:
@@ -276,7 +280,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 		:param repo:
 			The repository treeish are located in.
 
-		:param *treeish:
+		:param treeish:
 			One, two or three Tree Objects, Commits or 40 byte hexshas. The result
 			changes according to the amount of trees.
 			If 1 Tree is given, it will just be read into a new index
@@ -287,7 +291,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 			 being the common ancestor of tree 2 and tree 3. Tree 2 is the 'current' tree,
 			 tree 3 is the 'other' one
 
-		:param **kwargs:
+		:param kwargs:
 			Additional arguments passed to git-read-tree
 
 		:return:
@@ -790,7 +794,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 			removing the respective file. This may fail if there are uncommited changes
 			in it.
 
-		:param **kwargs:
+		:param kwargs:
 			Additional keyword arguments to be passed to git-rm, such
 			as 'r' to allow recurive removal of
 
@@ -828,7 +832,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 		:param skip_errors:
 			If True, errors such as ones resulting from missing source files will
 			be skpped.
-		:param **kwargs:
+		:param kwargs:
 			Additional arguments you would like to pass to git-mv, such as dry_run
 			or force.
 
@@ -924,7 +928,7 @@ class IndexFile(LazyMixin, diff.Diffable, Serializable):
 			explicit paths are given. Otherwise progress information will be send
 			prior and after a file has been checked out
 
-		:param **kwargs:
+		:param kwargs:
 			Additional arguments to be pasesd to git-checkout-index
 
 		:return:
diff --git a/lib/git/index/fun.py b/lib/git/index/fun.py
index ef950761..cc18c65c 100644
--- a/lib/git/index/fun.py
+++ b/lib/git/index/fun.py
@@ -51,8 +51,10 @@ def write_cache(entries, stream, extension_data=None, ShaStreamCls=IndexFileSHA1
 	:param entries: **sorted** list of entries
 	:param stream: stream to wrap into the AdapterStreamCls - it is used for
 		final output.
+		
 	:param ShaStreamCls: Type to use when writing to the stream. It produces a sha
 		while writing to it, before the data is passed on to the wrapped stream
+		
 	:param extension_data: any kind of data to write as a trailer, it must begin
 		a 4 byte identifier, followed by its size ( 4 bytes )"""
 	# wrap the stream into a compatible writer
@@ -103,7 +105,7 @@ def read_header(stream):
 
 def entry_key(*entry):
 	""":return: Key suitable to be used for the index.entries dictionary
-	:param *entry: One instance of type BaseIndexEntry or the path and the stage"""
+	:param entry: One instance of type BaseIndexEntry or the path and the stage"""
 	if len(entry) == 1:
 		return (entry[0].path, entry[0].stage)
 	else:
diff --git a/lib/git/index/typ.py b/lib/git/index/typ.py
index 7654b402..3a01cd65 100644
--- a/lib/git/index/typ.py
+++ b/lib/git/index/typ.py
@@ -78,10 +78,10 @@ class BaseIndexEntry(tuple):
 	def stage(self):
 		"""Stage of the entry, either:
 		
-			0 = default stage
-			1 = stage before a merge or common ancestor entry in case of a 3 way merge
-			2 = stage of entries from the 'left' side of the merge
-			3 = stage of entries from the right side of the merge
+			* 0 = default stage
+			* 1 = stage before a merge or common ancestor entry in case of a 3 way merge
+			* 2 = stage of entries from the 'left' side of the merge
+			* 3 = stage of entries from the right side of the merge
 		
 		:note: For more information, see http://www.kernel.org/pub/software/scm/git/docs/git-read-tree.html
 		"""
@@ -112,10 +112,10 @@ class IndexEntry(BaseIndexEntry):
 	See the properties for a mapping between names and tuple indices. """
 	@property
 	def ctime(self):
-		""":return:
-			Tuple(int_time_seconds_since_epoch, int_nano_seconds) of the
-			file's creation time
 		"""
+		:return:
+			Tuple(int_time_seconds_since_epoch, int_nano_seconds) of the
+			file's creation time"""
 		return unpack(">LL", self[4])
 
 	@property