docs: a little more

docs/objects.rst

@@ -134,24 +134,48 @@ creating the blob object:
 .. autofunction:: pygit2.hashfile
 
 
-
-
-
 Trees
 =================
 
 A tree is a sorted collection of tree entries. It is similar to a folder or
 directory in a file system. Each entry points to another tree or a blob.  A
 tree can be iterated, and partially implements the sequence and mapping
-interfaces::
+interfaces.
+
+.. method:: Tree[name]
+
+   Return the TreeEntry object for the given *name*. Raise ``KeyError`` if
+   there is not a tree entry with that name.
+
+.. method:: name in Tree
+
+   Return True if there is a tree entry with the given name, False otherwise.
+
+.. method:: len(Tree)
+
+   Return the number of entries in the tree.
+
+.. method:: iter(Tree)
+
+   Return an iterator over the entries of the tree.
+
+.. automethod:: pygit2.Tree.diff
+
+Tree entries
+------------
+
+.. autoattribute:: pygit2.TreeEntry.name
+.. autoattribute:: pygit2.TreeEntry.oid
+.. autoattribute:: pygit2.TreeEntry.hex
+.. autoattribute:: pygit2.TreeEntry.filemode
+
+Example::
 
-    >>> # Number of entries
     >>> tree = commit.tree
-    >>> len(tree)
+    >>> len(tree)                        # Number of entries
     6
 
-    >>> # Iteration
+    >>> for entry in tree:               # Iteration
-    >>> for entry in tree:
     ...     print(entry.hex, entry.name)
     ...
     7151ca7cd3e59f3eab19c485cfbf3cb30928d7fa .gitignore
@@ -161,24 +185,14 @@ interfaces::
     85a67270a49ef16cdd3d328f06a3e4b459f09b27 setup.py
     3d8985bbec338eb4d47c5b01b863ee89d044bd53 test
 
-    >>> # Get an entry by name
+    >>> entry = tree['pygit2.c']         # Get an entry by name
-    >>> entry = tree['pygit2.c']
     >>> entry
     <pygit2.TreeEntry object at 0xcc10f0>
 
-    >>> # Get the object the entry points to
+    >>> blob = repo[entry.oid]           # Get the object the entry points to
-    >>> blob = repo[entry.oid]
     >>> blob
     <pygit2.Blob object at 0xcc12d0>
 
-.. automethod:: pygit2.Tree.diff
-
-.. autoattribute:: pygit2.TreeEntry.name
-.. autoattribute:: pygit2.TreeEntry.oid
-.. autoattribute:: pygit2.TreeEntry.hex
-.. autoattribute:: pygit2.TreeEntry.filemode
-
-
 Creating trees
 --------------------
 

src/index.c

@@ -372,7 +372,7 @@ Index_read_tree(Index *self, PyObject *value)
 
 
 PyDoc_STRVAR(Index_write_tree__doc__,
-  "write_tree() -> str\n"
+  "write_tree() -> Oid\n"
   "\n"
   "Create a tree object from the index file, return its oid.");
 

src/repository.c

@@ -505,7 +505,7 @@ Repository_config__get__(Repository *self)
 }
 
 PyDoc_STRVAR(Repository_merge_base__doc__,
-  "merge_base(oid, oid) -> commit\n"
+  "merge_base(oid, oid) -> Oid\n"
   "\n"
   "Find as good common ancestors as possible for a merge.");
 
@@ -665,9 +665,9 @@ Repository_create_blob_fromdisk(Repository *self, PyObject *args)
 
 
 PyDoc_STRVAR(Repository_create_commit__doc__,
-  "create_commit(reference, author, committer, message, tree, parents[, encoding]) -> bytes\n"
+  "create_commit(reference, author, committer, message, tree, parents[, encoding]) -> Oid\n"
   "\n"
-  "Create a new commit object, return its SHA.");
+  "Create a new commit object, return its oid.");
 
 PyObject *
 Repository_create_commit(Repository *self, PyObject *args)
@@ -749,9 +749,9 @@ out:
 
 
 PyDoc_STRVAR(Repository_create_tag__doc__,
-  "create_tag(name, oid, type, tagger, message) -> bytes\n"
+  "create_tag(name, oid, type, tagger, message) -> Oid\n"
   "\n"
-  "Create a new tag object, return its SHA.");
+  "Create a new tag object, return its oid.");
 
 PyObject *
 Repository_create_tag(Repository *self, PyObject *args)
@@ -1209,12 +1209,11 @@ Repository_notes(Repository *self, PyObject *args)
     }
 
     return Error_set(err);
-
 }
 
 
 PyDoc_STRVAR(Repository_create_note__doc__,
-  "create_note(message, author, committer, annotated_id [,ref, force]) -> ID\n"
+  "create_note(message, author, committer, annotated_id [,ref, force]) -> Oid\n"
   "\n"
   "Create a new note for an object, return its SHA-ID."
   "If no ref is given 'refs/notes/commits' will be used.");

src/treebuilder.c

@@ -74,7 +74,7 @@ TreeBuilder_insert(TreeBuilder *self, PyObject *args)
 
 
 PyDoc_STRVAR(TreeBuilder_write__doc__,
-    "write() -> bytes\n"
+    "write() -> Oid\n"
     "\n"
     "Write the tree to the given repository.");