docs: a little more

Author: jdavid

docs/objects.rst

@@ -1,5 +1,5 @@
 **********************************************************************
-Git objects
+Git Objects
 **********************************************************************
 
 There are four types of Git objects: blobs, trees, commits and tags. For each
@@ -11,9 +11,42 @@ type.
    :local:
 
 
-Objects
+Object lookup
 =================
 
+In the previous chapter we learnt about Object IDs. With an oid we can ask the
+repository to get the associated object. To do that the ``Repository`` class
+implementes a subset of the mapping interface.
+
+.. method:: Repository.get(oid, default=None)
+
+   Return the Git object for the given *oid*, returns the *default* value if
+   there's no object in the repository with that oid. The oid can be an Oid
+   object, or an hexadecimal string.
+
+   Example::
+
+     >>> from pygit2 import Repository
+     >>> repo = Repository('path/to/pygit2')
+     >>> obj = repo.get("101715bf37440d32291bde4f58c3142bcf7d8adb")
+     >>> obj
+     <_pygit2.Commit object at 0x7ff27a6b60f0>
+
+.. method:: Repository[oid]
+
+   Return the Git object for the given oid, raise ``KeyError`` if there's no
+   object in the repository with that oid. The oid can be an Oid object, or
+   an hexadecimal string.
+
+.. method:: oid in Repository
+
+   Returns True if there is an object in the Repository with that oid, False
+   if there is not.  The oid can be an Oid object, or an hexadecimal string.
+
+
+The Object base type
+====================
+
 The Object type is a base type, it is not possible to make instances of it, in
 any way.
 
@@ -51,40 +84,59 @@ This is the common interface for all Git objects:
 .. automethod:: pygit2.Object.read_raw
 
 
+Blobs
+=================
+
+A blob is just a raw byte string. They are the Git equivalent to files in
+a filesytem.
 
+This is their API:
 
+.. autoattribute:: pygit2.Blob.data
 
+   Example, print the contents of the ``.gitignore`` file::
 
+     >>> blob = repo["d8022420bf6db02e906175f64f66676df539f2fd"]
+     >>> print blob.data
+     MANIFEST
+     build
+     dist
 
-Blobs
-=================
+.. autoattribute:: pygit2.Blob.size
 
-A blob is equivalent to a file in a file system.::
+   Example::
 
-    >>> # create a blob out of memory
-    >>> oid  = repo.create_blob('foo bar')
-    >>> blob = repo[oid]
-    >>> blob.data
-    'foo bar'
-    >>> oid
-    '\x96\xc9\x06um{\x91\xc4S"a|\x92\x95\xe4\xa8\rR\xd1\xc5'
+     >>> print blob.size
+     130
 
-.. autoattribute:: pygit2.Blob.data
-.. autoattribute:: pygit2.Blob.size
+Creating blobs
+--------------
 
-To create new blobs use the Repository API:
+There are a number of methods in the repository to create new blobs, and add
+them to the Git object database:
 
 .. automethod:: pygit2.Repository.create_blob
+
+   Example:
+
+     >>> oid  = repo.create_blob('foo bar')   # Creates blob from bytes string
+     >>> blob = repo[oid]
+     >>> blob.data
+     'foo bar'
+
 .. automethod:: pygit2.Repository.create_blob_fromworkdir
 .. automethod:: pygit2.Repository.create_blob_fromdisk
 
-It is also possible to get the oid for a blob without really adding it to
-the Git object database:
+There are also some functions to calculate the oid for a byte string without
+creating the blob object:
 
 .. autofunction:: pygit2.hash
 .. autofunction:: pygit2.hashfile
 
 
+
+
+
 Trees
 =================
 

docs/repository.rst

@@ -9,16 +9,19 @@ existing one.
    :local:
 
 
-Creating a repository
+Functions
 ===================================
 
 .. autofunction:: pygit2.init_repository
 
-Example::
+   Example::
+
+     >>> from pygit2 import init_repository
+     >>> repo = init_repository('test')            # Creates a non-bare repository
+     >>> repo = init_repository('test', bare=True) # Creates a bare repository
+
+.. autofunction:: pygit2.discover_repository
 
-  >>> from pygit2 import init_repository
-  >>> repo = init_repository('test')            # Creates a non-bare repository
-  >>> repo = init_repository('test', bare=True) # Creates a bare repository
 
 
 The Repository class
@@ -47,9 +50,3 @@ Below there are some general attributes and methods:
 .. autoattribute:: pygit2.Repository.is_empty
 .. automethod:: pygit2.Repository.read
 .. automethod:: pygit2.Repository.write
-
-
-Utilities
-=========
-
-.. autofunction:: pygit2.discover_repository

src/blob.c

@@ -42,7 +42,8 @@ Blob_size__get__(Blob *self)
 
 
 PyDoc_STRVAR(Blob_data__doc__,
-  "Raw data. This is the same as Blob.read_raw()");
+  "The contents of the blob, a bytes string. This is the same as\n"
+  "Blob.read_raw()");
 
 PyGetSetDef Blob_getseters[] = {
     GETTER(Blob, size),

src/repository.c

@@ -592,9 +592,10 @@ Repository_walk(Repository *self, PyObject *args)
 
 
 PyDoc_STRVAR(Repository_create_blob__doc__,
-  "create_blob(data) -> bytes\n"
-  "\n"
-  "Create a new blob from memory.");
+    "create_blob(data) -> Oid\n"
+    "\n"
+    "Create a new blob from a bytes string. The blob is added to the Git\n"
+    "object database. Returns the oid of the blob.");
 
 PyObject *
 Repository_create_blob(Repository *self, PyObject *args)
@@ -616,9 +617,11 @@ Repository_create_blob(Repository *self, PyObject *args)
 
 
 PyDoc_STRVAR(Repository_create_blob_fromworkdir__doc__,
-  "create_blob_fromworkdir(path) -> bytes\n"
-  "\n"
-  "Create a new blob from a file within the working directory (raise an error otherwise).");
+    "create_blob_fromworkdir(path) -> Oid\n"
+    "\n"
+    "Create a new blob from a file within the working directory. The given\n"
+    "path must be relative to the working directory, if it is not an error\n"
+    "is raised.");
 
 PyObject *
 Repository_create_blob_fromworkdir(Repository *self, PyObject *args)
@@ -639,9 +642,9 @@ Repository_create_blob_fromworkdir(Repository *self, PyObject *args)
 
 
 PyDoc_STRVAR(Repository_create_blob_fromdisk__doc__,
-  "create_blob_fromdisk(path) -> bytes\n"
-  "\n"
-  "Create a new blob from a file anywhere (no working directory check).");
+    "create_blob_fromdisk(path) -> Oid\n"
+    "\n"
+    "Create a new blob from a file anywhere (no working directory check).");
 
 PyObject *
 Repository_create_blob_fromdisk(Repository *self, PyObject *args)