Merge remote-tracking branch 'michaeljones/documentation'

docs/general.rst

@@ -6,14 +6,45 @@ General
    :local:
 
 
+Top level constants and exceptions from the library.
+
 Constants
 =========
 
-.. py:data:: LIBGIT2_VER_MAJOR
-.. py:data:: LIBGIT2_VER_MINOR
-.. py:data:: LIBGIT2_VER_REVISION
-.. py:data:: LIBGIT2_VER_VERSION
+The following constants provide information about the version of the libgit2
+library that has been built against. The version number has a
+``MAJOR.MINOR.REVISION`` format.
 
+.. py:data:: LIBGIT2_VER_MAJOR
+
+   Integer value of the major version number. For example, for the version
+   ``0.20.0``::
+
+      >>> print LIBGIT2_VER_MAJOR
+      0
+
+.. py:data:: LIBGIT2_VER_MINOR
+
+   Integer value of the minor version number. For example, for the version
+   ``0.20.0``::
+
+      >>> print LIBGIT2_VER_MINOR
+      20
+
+.. py:data:: LIBGIT2_VER_REVISION
+
+   Integer value of the revision version number. For example, for the version
+   ``0.20.0``::
+
+      >>> print LIBGIT2_VER_REVISION
+      0
+
+.. py:data:: LIBGIT2_VERSION
+
+   The libgit2 version number as a string::
+
+      >>> print LIBGIT2_VERSION
+      '0.20.0'
 
 Errors
 ======
@@ -22,3 +53,4 @@ Errors
    :members:
    :show-inheritance:
    :undoc-members:
+

docs/references.rst

@@ -27,6 +27,23 @@ The Reference type
 .. automethod:: pygit2.Reference.resolve
 .. automethod:: pygit2.Reference.log
 .. automethod:: pygit2.Reference.log_append
+
+   Example::
+
+      >>> branch = repository.lookup_reference("refs/heads/master")
+      >>> branch.target = another_commit.id
+      >>> committer = Signature('Cecil Committer', 'cecil@committers.tld')
+      >>> branch.log_append(another_commit.id, committer,
+                            "changed branch target using pygit2")
+
+   This creates a reflog entry in ``git reflog master`` which looks like::
+
+      7296b92 master@{10}: changed branch target using pygit2
+
+   In order to make an entry in ``git reflog``, ie. the reflog for ``HEAD``, you
+   have to get the Reference object for ``HEAD`` and call ``log_append`` on
+   that.
+
 .. automethod:: pygit2.Reference.get_object
 
 
@@ -45,7 +62,7 @@ Example. These two lines are equivalent::
 Branches
 ====================
 
-Branches inherit from References, and additionally provide spetialized
+Branches inherit from References, and additionally provide specialized
 accessors for some unique features.
 
 .. automethod:: pygit2.Repository.listall_branches

docs/repository.rst

@@ -33,6 +33,11 @@ Functions
 
 .. autofunction:: pygit2.discover_repository
 
+   Example::
+
+     >>> current_working_directory = os.getcwd()
+     >>> repository_path = discover_repository(current_working_directory)
+     >>> repo = Repository(repository_path)
 
 
 The Repository class

src/reference.c

@@ -202,7 +202,10 @@ Reference_resolve(Reference *self, PyObject *args)
 PyDoc_STRVAR(Reference_target__doc__,
     "The reference target: If direct the value will be an Oid object, if it\n"
     "is symbolic it will be an string with the full name of the target\n"
-    "reference.");
+    "reference.\n"
+    "\n"
+    "The target is writable. Setting the Reference's target to another Oid\n"
+    "object will direct the reference to that Oid instead.");
 
 PyObject *
 Reference_target__get__(Reference *self)